MacTech 1 to 12

home *** CD-ROM | disk | FTP | other *** search

/ MacTech 1 to 12 / MacTech-vol-1-12.toast / Source / MacTech® Magazine / Volume 07 - 1991 / Goodies Disk / EnterAct ƒ / EnterAct 1.4 Manual(no PICTs) next >

Wrap

Text File | 1991-09-16 | 147.8 KB | 2,489 lines | [TEXT/KEEN]

************************ENTERACT USER’s MANUAL********************** Copyright © 1991 by Dynabyte. Portions Copyright © 1987 by Symantec Corporation. EnterAct 2, by Ken Earle. All rights reserved. NOT FOR USE ON NETWORKS ----------------------------------------------------------------- This manual is actually for version 1.4 of EnterAct, the only omission being that version 2 comes with Drag_on Modules (separate CODE resource commands), which are not included with the demo version of EnterAct. The demo version of EnterAct has restricted file-saving capabilities, and you should use it for reviewing existing code rather than creating new code. The real version of Enteract 2 comes with a powerful Macintosh version of AWK, including the full source code—you can easily adapt your application to call it if you like. And you also get a printed manual, and a 60-day money back guarantee—so after a little dabbling here, try the real thing! ----------------------------------------------------------------- System 6 or 7 required. Mac II speed (that is, a 68000 running at 16 mHz) is recommended if your project contains more than about 500K of text in source and header files combined. A hard disk is a practical necessity. A large screen (larger than 512 by 342) will allow you to take better advantage of EnterAct’s main innovation, the ability to retrieve definitions or prototypes from your project to separate “Lookup” windows—these are “self–placing” windows, and management of these windows is entirely reduced to the initial press of the <Enter> key that calls them up, provided only that you leave a bit of your screen free for them to find a home. EnterAct is intended for creating, maintaining, and reviewing THINK C™ code. There are no known incompatibilities with MPW C™, but testing there has not been extensive, so the only guarantee there is that if you report a problem with MPW C a fix will be concocted and sent to you as soon as possible. PLEASE NOTE if you use markers they will be maintained properly only by programs that implement MPW–compatible markers. In particular, if you edit a marked file with THINK C version 4 the marks will be thrown off. See the discussion at the end of “Markers and Automark” for a relatively painless workaround. This document contains nearly the entire text of the printed manual, but lacks much of the typesetting of the printed version, and all of the illustrations, alas. The benefits of having it on disk are that you can use Find on the table of contents and elsewhere to jump to topics of interest, and that this document is marked with chapter headings (albeit in alphabetical order)—hold down the <Command> key and click in the title bar to view the marks menu for this file. Aside from that, it really reads better on paper. Tech support/order information: 1-416-595-9440. For the licence, please see the printed version. CONTENTS (the page numbers are a bit off...) Introduction 1 Getting started 2 Some definitions 3 <Enter> and <Option> 7 Whirlwind tour 9 Not everything goes 21 Projects 25 Introduction 25 What a project must contain 25 Creating a project 25 Three panes—.c, .h, plain text 26 Add Files—the old–fashioned way 26 Add All Files In Folder—the fast way 26 Add Mac Headers 27 Add Standard C Headers 28 Remove File 28 Custom file extensions 28 Distinguishing ".h" from <.h> 29 Copy and Search in the project window 29 Tips 30 Dictionaries 31 Introduction 31 What's in a dictionary 31 Building your dictionary 32 Keeping it up to date 33 How long will it take? 33 Show Dictionary 34 If there’s a problem 34 Lookup 37 Introduction 37 Click, press <Enter> 37 Press <Enter> again to see more entries 38 Your spelling 39 Hints for speedup 40 Number of lookup windows 41 Number of entries per lookup 42 Keeping lookups around 42 AutoLook 42 Paste Selection Behind 43 Editing an entry is temporary 44 If there’s a problem 44 Browsing 45 The Browse command 45 Browsing classes without the browser 46 Browsing methods without the browser 46 Editing 49 Introduction 49 The usual stuff 49 Undo 49 Typing, Cut, Copy, Clear 50 Paste preserves indentation 50 Selections: front, next–to–front 51 Paste Selection Behind 51 Font, font size, tabs 52 Shift Left / Right 53 Reformat Selection 54 Arrow keys for moving around 55 Go to 55 If there’s a problem 56 Balance 57 Checks everything 57 Shows the error location 58 Balancing a file 58 Balancing a specific delimiter 59 Nested and bad comments 59 Starting in the middle 61 Diagnosing a problem 62 The asm problem 63 Search 65 Introduction 65 Find is modeless 65 Find options 66 <Tab> and <Return> 67 Find Again 67 Enter Selection 67 Recent finds are remembered 67 Replace 67 Replace and Find Again 68 Replace All 68 Multi-file Searches 68 Markers and Automark 69 Documents and windows 71 New, Open, Close 71 Save, Save As, Revert 71 Saving window locations 71 …without being pestered 72 Newly opened windows can be long or short 72 <Option>Zoom zooms just the length 73 Number of windows at one time 73 The Windows menu 73 The display box 74 Printing 75 Options, under the Edit menu 77 Introduction 77 Number of lookup windows 77 Number of entries per lookup window 77 Remembering window locations 78 Long or short windows 78 Reformat Selection options 78 Detect nested comments 78 Switching to other applications 79 Under the Finder 79 Under MultiFinder 79 Check the disk for changes 80 Lookup tips 81 Looking up your notes 81 When in doubt 82 Seeing where a term is defined 83 <Option>double–click 83 Find Definition 83 If there are multiple definitions 83 Some thoughts on using EnterAct 85 Projects are cheap 85 Learning from or reviewing code 86 If lookup is too slow 86 Balance your files 86 If it moves, document it 87 If there's a problem 89 Out of memory 89 Missing dictionary entries 89 Dictionary build problems 90 Lookup problems 94 Balance problems 95 ---------------------------------------------------------- Introduction ---------------------------------------------------------- Feeling slightly disoriented? That’s just the anesthetic wearing off. You now have several megabytes of fast memory installed in your head, preloaded with details about everything of interest in all of your C projects. To access your new memory, click just to the right of any function, struct, define, etc that you’d like to see a definition for, and press <Enter>. Welcome to EnterAct. If you’re already travelling at light speed, prepare for warp drive. If you’re learning C, you’ll find that the ability to look up anything of potential interest gives you more than total recall—you now have an on–line personal tutor. This manual is not as impersonal as most. My name is Ken Earle, I’m responsible to you for EnterAct’s performance, and if you have any problems using EnterAct that this manual doesn’t answer please see the “Tech support” section at the end of this manual for my phone number and hours. If you’ve done some programming in C on the Mac, you’ll find that EnterAct is mostly familiar territory. EnterAct is intended to complement THINK C, which you will need for compiling and testing your code. For creating, maintaining, learning from, and documenting code—read on. 60 second warmup EnterAct uses a project window to keep track of your files, as does THINK C for example. However, the main purpose of an EnterAct project is to allow you to build a dictionary of all terms in your project, for rapid lookup. There are three panes in an EnterAct project window, containing your .c, .h, and plain text files from left to right respectively. The easiest way to add files to your project is to use the “Add All In Folder...” command. To build a dictionary, select “Update Dictionary”. Unless there are major errors in your source code, this will zip along at 2-3 files per second. Double–click on any file name in the project window to view a file. To look up a term, select an insertion point just to the right of the term (or of course type it in) and press <Enter>. Activating the “AutoLook” window provides constant lookup as you work. What next? After “Getting started”, arm yourself with “Some definitions” and then take the tour. Browse through the rest of the manual, experiment a bit, reassess your ability to handle complexity, put your new memory to work. And remember, take a break every hour! ---------------------------------------------------------- Getting started ---------------------------------------------------------- Installation Install EnterAct in the same folder where you keep THINK C, at the same level. This will allow EnterAct to distinguish between your ".h" and your <.h> files, among other things. If you don’t have a set of prototypes for toolbox calls, and would like one, copy the “MacProto's.h” file to your “Mac #includes” folder. There is a copy of this manual on the disk also (illustrated, but lacking the typesetting). It’s rather huge, the illustrations will show only if you open it with EnterAct, and it’s definitely optional. What to do first If you don’t feel comfortable using your Macintosh yet, please take an hour or so to play with some other program before continuing. If there’s a “Read me” file on the disk, it will describe minor changes not listed in this manual. The Whirlwind tour will introduce you to the most important things. After a bit of pushing the <Enter> key and and playing with your new memory, I’d recommend you explore the Paste Selection Behind , Balance, and Automark commands, and the lookup options available to you in the Options dialog. EnterAct can be used as a decent browser of classes and methods, as described in “Browsing”. If you use MultiFinder, there are some important things about EnterAct you should know first, discussed in the “Switching to other applications” chapter. What to memorize The uses of the <Enter> and <Option> keys (there aren’t that many). They’re listed a couple of pages ahead. What to watch out for If you’re a multi–platform developer, please read the “Not everything goes” section on “All–or–nothing macro’s”. What to do eventually Read the manual, or at least browse through it. The table of contents serves as an index of the important things, and there’s a menu reference at both ends of this manual. The “If there’s a problem” sections are primarily there to be consulted when you have a problem, and are not required reading. Several of EnterAct’s features have been added at the request of users. If you’d like to see anything added to EnterAct, please send me a note about it, the more details the better. No ask, no get! ---------------------------------------------------------- Some definitions ---------------------------------------------------------- Bold face in the text is used only for menu commands. Menu commands are sometimes used in this manual as verbs, for example “when you Balance a comment...”. Key–equivalents for menu commands are shown at the end of this manual. Insertion point: the flashing “|” cursor which marks your place in a text window when no characters are selected. Range of characters selected: white text on a black background in the front window, seen for example when you drag over some text. In the next–to–front window, the selection range is shown outlined in a black box rather than white on black (the next– to–front window is affected by Paste Selection Behind, and by some Search commands when the Find dialog is in front). Specific keys are placed in <>, eg <Enter>, <Option>, <Return>. C code is shown in Courier 10. Dictionary: the collection of terms and definitions for your project. Term: anything defined or mentioned outside of a function, struct, or union body. Definition or Entry: for functions and methods, the prototype or equivalent is shown. For everything else (struct, #define, variable, etc), the full statement in which the term was mentioned or defined is shown. Lookup window: a special kind of text window used to show dictionary entries. The title always begins with “••” or “¶¶”. Often several entries are “stacked” in one lookup window; to cycle through them, press <Enter> with a range of characters selected. Look up a term: to look up a term, select an insertion point just to the right of it and press <Enter>. Up pops a lookup window. Project: a three–pane window containing any group of source, header, plain text, and PICT documents. Selecting Update Dictionary builds a dictionary for all source and header files. Double–clicking on a file shown in the project window will both open the file and send the project window behind all other windows. It can be brought to the front again with the Windows menu, or <Command><zero> if it’s hidden. Paste Selection Behind: will Copy the selection in the front window, switch to the next window, and Paste over what is selected there. The selection in the next–to–front window will be shown by a two–pixel wide black border. Paired delimiters: () round brackets, or parentheses [] square brackets {} braces, or curly braces /* */ comment start and end, together a comment " " double quotes (continued across lines with “\”) ' ' single quotes, or ticks. Balance: checks all paired delimiters, and detects nested or improperly–formed comments. If you have an insertion point at the very beginning of the file, Balance will check the entire file. If there’s an imbalance, you’ll see where it is. Reformat Selection: evens out the line lengths in a range of selected text, with maximum line length and ragged right versus full justification as specified in the Options dialog. Intended for use with comments or plain text, rather than code. Find Definition: given a selected dictionary term, opens the file where the term is defined and scrolls to the first instance of the term in the file. The equivalent of <Option>double–click, but in addition works with full method names, which contain colons. ---------------------------------------------------------- <Enter> and <Option> ---------------------------------------------------------- <Enter> To look up the definition of a term, select an insertion point just to the right of it, or type the term, and press <Enter>. Lookup windows can often show more than one entry. To view the next entry, press <Enter> with a range of characters selected. A range of characters is selected for you automatically when an entry is first shown, allowing you to cycle through entries by repeatedly pressing <Enter>. The number of the current entry you are viewing, and the total number of entries available, are shown in the display box at the bottom of the lookup window, eg “1/4”, “3/7”. To view the previous rather than next entry in a lookup window, hold down the <Option> key while pressing <Enter>. Looking up a definition for a term in a lookup window is the same as for any other text window—select an insertion point just to the right of it, or type the term, and press <Enter>. Pressing the <Enter> key when your selection range or insertion point is not visible will just scroll one end or the other of it into view. <Option> Holding down the <Option> key while double–clicking on a term will open the file where the term is defined, and will usually scroll to the definition. This doesn’t work with full method names which contain colons; for these, select the entire name on both sides of the two colons and use the Find Definition command, which does the equivalent of <Option> double–click on anything you select. Although your spelling must be correct in order for this to work, you can always look the term up to find the correct spelling, and then <Option> double–click on the name shown in the lookup window. To modify the files selected for a multi–file search, hold down the <Option> key and drag over files directly in the project window. You can also use the <Command> key for this. A bullet • appears in the project window to the left of each file included in the search. EnterAct will automatically scroll your text windows left and right as well as up and down. The quickest way to return to viewing the left margin is to press <Option><left arrow>, which will also move your insertion point to the left margin. ---------------------------------------------------------- Whirlwind tour ---------------------------------------------------------- Hum along This little tour is more a suggestion of the order in which you should try things than a set of specific examples. Think of some C files you’d like to try EnterAct on, and fire up your Mac. Installation Copy EnterAct to the same folder where you have THINK C, at the same level. Create a project Double–click on the EnterAct icon to start. You will see a dialog asking if you want to open an existing project—cancel it. Another dialog will appear, asking you to supply a name for a new project. Type in a name (such as “test.e”), select a folder in which to save your new project, and click the Save button. A three–pane project window will appear. Add some files You can add files to your project one at a time with the Add Files command—but try the Add All In Folder command instead: it works exactly the same as the Add Files command, but when you select one file and click the Add button all other text files in the folder will be added to your project as well. However, files contained in sub–folders are not added automatically. PICT files can only be added one at a time, with the Add Files command. There is no need to ever select one of the three window panes when adding files. The left pane is for your source files (.c), the middle for all header files (.h), and the right pane is for all other text files (and PICT’s). EnterAct selects the correct pane for each file automatically. For this tour, it’s probably best to just add code files that you know are compilable, saving your not–quite–ready–for–prime–time files for your first real project after this one when you’ve seen the basics. The files you add don’t have to add up to a THINK C project, no specific header files are required, and no non–text files such as libraries need to be added. For this first example, you might want to select Add Mac Headers instead of Add All In Folder. This will give you a perfectly adequate project consisting of the standard “Mac #includes” header files, Quickdraw.h etc. Build a dictionary Your dictionary will contain all terms in your .c and .h files that are defined or mentioned outside of a function, struct, or union body. To build, it, select Update Dictionary from the Project menu, and sit back for a few seconds—this shouldn’t take long, typically 1/2 second per file on a Mac II. If a major bug does interrupt the dictionary build, you’ll see a message telling you what’s up. You can either fix the bug and reselect Update Dictionary, or, with the offending file selected in the project window, select Remove File followed by Update Dictionary to go on with this tour immediately. Two special cases: if the error is "Unbalanced comment", due to a second comment start within a comment, you can use the Options command and uncheck the “Detect nested comment starts” option to get around this; and if the problem seems to be due to a macro, see the “All–or–nothing macro’s” section in the “Not everything goes” chapter for ways to get around this one. Entering the macro name in the "Macro's to skip..." dialog, as explained there, will usually do the job. EnterAct needs about 300K of memory minimum, but your entire dictionary is also kept in memory and this uses roughly one–half the total size of all .h and .c files that you add to the project. If in doubt, use “Get Info” on your source and header folders while in the Finder to determine the total size of all your source and header files—then divide by two and add 300K to see how much memory you’ll need. Start looking things up Open any .c or .h file by double–clicking on it in the left or middle scrollable project window panes. You can look up any function, method, struct class union or enum tag, enum constant, #define, typedef, or variable (including low–memory and statics) that is defined or mentioned anywhere in your .c or .h project files outside of a function, struct, or union body. In other words, just about everything of interest except local variables or any other “thing” which is meant to be used only within a single specific function. Find a term you’d like to look up, click just to the right of it (no text selected, just a flashing insertion “I-beam” cursor) and press the <Enter> key. Or type in the name of a term and press <Enter>. A dictionary entry for the term will appear in a new small text window, called a “lookup” window. Lookup windows are mostly like text windows, the key differences being that they cannot be directly saved (Copy and Paste to a real text window to do that), and they usually can show you other dictionary entries. Only one is shown at a time. Lookup windows In the small display box along the bottom of the lookup window you will see: the name of the file from which the entry was taken; the kind of term it is (a one–letter abbreviation, for example “v” for variable, “(” for a function, “s” for a struct); and two numbers—the current entry you are viewing, followed by the total number of entries currently stored in the lookup window. The title of the lookup window will be the term you wanted looked up, preceded by two bullets, eg “••EventDetails”. The two bullets are a sign that the window is a lookup window, not a regular document window. The AutoLook window Now is a good time to activate the AutoLook window, by selecting AutoLook from the “EnterAct” menu. It explains itself. Keeping the lookup around You can adjust the maximum number of lookup windows you wish to have on–screen at one time, with the Options command: when this limit is reached and you press <Enter> to see another lookup, one of the lookup windows that is currently on–screen will quietly go away to make room for the new one. To prevent this happening to a lookup window that you’d like to keep around, select Keep Lookup Around from the windows menu while the lookup window is in front. It will then stay on–screen until you Close it, or until you Close the project. When you “keep around” a lookup window the two bullets “••” at the start of the window title will change to “¶¶” to help you distinguish the keepers from the ones that might go away later. Viewing other entries With at least one character selected in the lookup window, press the <Enter> key to view the next entry in the lookup window. A selection is automatically made for you, so in practice you can press <Enter> as soon as the lookup window appears to see other entries without having to use the mouse. Pressing <Enter> when you reach the last entry will return you to the first entry. The <Enter> key In any text window including lookup windows, pressing the <Enter> key with an insertion point means “look it up”. The I–beam should be just to the right of the term you want looked up. Pressing the <Enter> key when characters are selected never activates lookup. In lookup windows, pressing <Enter> with characters selected means “show me the next match”, whereas in regular text windows nothing much will happen—it will jump your selection into view if you’ve scrolled away, but that’s it. So: to look up a term in any window, click just to the right of it and press <Enter>, or type it and press <Enter>; and to cycle through the matches in a lookup window, press <Enter> when characters are selected. Looking up something in a lookup window It’s the same as any text window—click to get an insertion point just to the right of the name you want looked up, and press <Enter>. If your spelling is correct If your spelling matched some term in your dictionary exactly, all the entries will be for the same name. However, you can use the same name in different “name spaces” in C, and your dictionary will also hold all variations of any particular type. For example, if your source code contains: typedef int Name; and long *Name(int x) {-function definition-} and extern long *Name(int x); then the lookup window for Name will show you three different entries as you cycle through them with the <Enter> key—one typedef, and two variations for the function. If your spelling is off If your spelling did not match any term in your dictionary exactly, then you’ll see whatever entries come closest, with all variations as above. The entries will be presented in order from best match to worst as you press <Enter>. EnterAct is roughly as good at judging what’s close as you would be if you made no allowance for synonyms or getting things backwards. EnterAct’s lookup power is sufficient that one guideline is all you need: when you’re not sure of the correct spelling, type your best guess, remembering that C is case–sensitive. EnterAct will almost always retrieve what you want on the first try. Using lookup windows EnterAct comes preset with a maximum of four lookup windows on–screen at one time, and a maximum of four entries per lookup window. You can change these limits at any time by selecting the Options command under the Edit menu. For complex problems, you may want more lookup windows. If your recollection of the spelling of a term has gone out the window, you may want to temporarily increase the number of alternate entries returned per lookup window. You can vary the number of lookup windows from 1 to 10, and the number of entries per window from 1 to 20. Seeing where a term is defined Select the entire term, and choose Find Definition. This will open the file where the term is defined, and will usually show you the defining instance of the term. <Option>double–clicking on a term does the same thing, but doesn’t work with full method names, which consist of two words separated by colons. For those, you will need to use Find Definition. For more on this, see the “Browsing” chapter. Paste Selection Behind Once you get used to it, Paste Selection Behind can replace many of the Pastes you do when creating code. Given a selection in your front window, Paste Selection Behind will; Copy the selection, bring the next–to–front window to the front, and Paste what was copied into the new front window. This is undoable, and the selection in your next–to–front window is shown outlined beforehand to help you anticipate what will happen. Paste Selection Behind is especially handy with lookup windows—switch to a lookup window, select a member name or prototype, and Paste Selection Behind takes you back to your working window with what you want pasted in. Balance Balance checks all of the paired delimiters in C (with the picky exception of angle brackets <>). If you select an insertion point at the top of a file (with <Option><up arrow>, or Go Top), Balance will balance your entire file. If any error in balance is detected, you’ll be shown the mismatched or unmatched delimiter. When balancing a file, if you hear a beep and the insertion point remains at the top of the file, that means your whole file balanced. Balance also detects nested comments, and more importantly any single failure to properly start or end a comment, something even most compilers don’t do. There is a minor penalty to pay for this improved checking: you can’t use a comment start or end within a comment. If you do have a comment start or end within a comment, putting a space between the '*' and the '/' will render it harmless. Since EnterAct’s dictionary–builder checks comments fully, simply by building the dictionary you will guarantee that no improper comment in any of the included source files will ever generate a wild pointer or an uninitialized variable. Searching The Find dialog in EnterAct is modeless, which means that when the Find dialog is in front any search command you pick will apply to the window just behind it. An important exception is Replace All, which is not undoable and works only when a text window is in front. The little buttons in the lower–right of the Find dialog allow to to set up a general multi–file search of your project files. As you click them, you’ll see bullets appear beside files to be searched in your project window. To “fine–tune” your multi–file search selection, hold down the <Option> key and click on or drag over the file names right in the project window. A popup menu at the top of the Find dialog remembers the 20 most recent strings of characters that you have searched for. Little things If you hold down the <Option> key while clicking in the zoom box of a window, only the length will be affected—the bottom of the window will grow down to the bottom of your screen. When you double–click on a file in the project window to open the file, the project window will retreat behind all other windows. If you lose sight of the project window, you can bring it to the front by selecting it from the Windows menu or using the key command <Command><zero>. Even on small screens this allows you to have a large project window and use it conveniently as a “mini Finder”. Paste preserves relative indentation, at least in the commonest situations where you would want your indentation to be retained. Most of the time you won’t need to use Shift Left or Shift Right after pasting in a block of code. If you don’t get it working first try, see the “Paste preserves indentation” section in the “Editing” chapter. You can Copy a file name from the project window. Windows remember their last saved location, unless you select otherwise from the Options dialog. Under MultiFinder, EnterAct takes special care of your text documents (see “Switching to other applications”). Reformat Selection is handy for making comments pretty again after you’ve chopped them up (it’s undoable, and some Options are available). There are some other things worth trying out, especially markers, but you’ll find them easily as you browse through the rest of this manual. Did I say browse? When you build yourself a project that contains classes, try out the Browse command to see a graphic view of your classes. Double–click on a class name to view the class definition, click–and–hold briefly on a class name to select from a list of methods, and then view the method definition. If you’re new to C++ and all that, you’ll find no better way to learn than by exploiting EnterAct’s project–building, lookup, and browsing power—in fact, you might want to build a project for THINK C’s ArtClass demo right now. Incidentally, here’s a shortcut to adding all of the source and header files in THINK C’s class library folder: first add a dummy text file (call it “_junk” or somesuch) at the top level of the folder containing the source and header folders; then hold down all three of the <Shift>, <Option>, and <Command> keys while selecting the Add All In Folder command; double–click on your “_junk” file and all files in all subfolders will be added to your project. Dictionary restrictions There are three sorts of code constructions that are nominally correct, but throw off EnterAct’s dictionary–builder. Please read the next chapter “Not everything goes” if the very notion bothers you, or trust my assertion that unless you are doing sophisticated cross–platform development, the one restriction of the three that you might ever conceivably encounter will not apply. If you’ve tried things out for yourself while taking this tour, I expect you know enough about EnterAct to begin using it full–time for code creation and review—aside from knowing when to poke the <Enter> and <Option> keys, there isn’t much to it. Eventually, alas, you should probably read the rest of the manual. Personally, I enjoy reading manuals. ---------------------------------------------------------- Not everything goes ---------------------------------------------------------- EnterAct is able to identify terms in your code and correctly deduce the type and definition of each term without doing extensive preprocessing or semantic analysis. The benefits are lightning speed and considerable tolerance of first–draft errors. The drawback is that EnterAct cannot deal with absolutely everything that is possible in C, and three minor restrictions must be satisfied in order for the dictionary–builder to deal properly with your code. In practice, only the “illegal aliases” will stop the dictionary builder, whereas noncompliance with the other two restrictions will result in extra or missing dictionary entries for some terms. Aliases Defined equivalents for certain keywords and punctuation should be avoided. A defined equivalent or alias takes the form #define Record struct for example. EnterAct won’t know that “Record” is supposed to mean “struct”, and the dictionary–builder won’t work well at all. The complete list of keywords that should not be aliased: asm enum pascal Pascal struct typedef union void class The complete list of punctuation that should not be aliased: ; : , \ " ' {} () [] / * = You will never see aliases for any of these in published code, or in any code intended to be read by more than one person, for the simple reason that such a creature as Record fileData BEGIN int x SEMI END SEMI would be rather difficult for anyone but the author to read. Other aliases, such as #define EQ == are perfectly OK, by the way. Obviously unnecessary parentheses These are just as rare as the aliases above. This restriction applies only outside of function bodies and refers only to parentheses that would result in a variable declaration resembling a function declaration. An example would be Peter (Harvey); Right now you know as much as EnterAct does when it runs into this sort of thing—is it a variable declaration or a function declaration? You may have deduced that the above declaration is almost certainly for a function “Peter” returning an (implicit) int, since you would never type those parentheses in a simple variable declaration, int (x); —these are an example of what is meant by “obviously unnecessary parentheses”, namely parentheses that make the code harder to read, not easier. If you avoid these excessive parentheses when declaring variables outside of a function, that’s all that’s needed. Once again, you won’t see them in any published code, and even beginners feel that such parentheses make life harder, not easier. All–or–nothing macro’s This final restriction is one that you may run into. An “all–or–nothing” macro is a macro that looks something like #ifdef BLUETREECOMPILER #define P(x) x #else /* some other compiler */ #define P(x) #endif —so P(x) either does nothing at all to its argument or it “eats” the argument, but either way the macro itself disappears from the code. If such a macro is the very first thing in a statement then EnterAct will deal with it correctly, for example P(typedef int INT16;) would result in INT16 being recorded as a typedef’d equivalent of “int”. However, if the all–or–nothing macro is not the very first thing in the statement, as in int myFunc P((int x, long y)); then EnterAct will mistakenly record “P” and not “myFunc” as the function name, and in general it will misrecord any similar statement where an–or–nothing–macro isn’t the first thing in the statement. In case you’re wondering, the intention of int myFunc P((int x, long y)); is to produce either int myFunc (int x, long y); or int myFunc (); - in other words either a proper modern prototype or an old–fashioned declaration, and this sort of thing is useful when writing code that will be compiled using different compilers. What to do? Call up the "Macro's to skip..." dialog from the EnterAct menu, and enter the name of the macro there. If there is still a problem, please give tech support a call—given a full description of your macro trouble, we will probably be able to come up with a fix. ---------------------------------------------------------- Projects ---------------------------------------------------------- Introduction Any collection of TEXT or PICT files from up to 6 disks can be added to an EnterAct project. Use New Project, followed by Add Files or Add All In Folder, and then Update Dictionary to build a complete project. Even if 200 files are involved the whole process from start to finish shouldn’t take more than three minutes on a Mac II. What a project must contain TEXT or PICT files. The source and header files don’t have to add up to a compilable application—anywhere from one file to part or all of the source and documentation for several applications can be an EnterAct project. The only limits are available memory and the nuisance of having slower lookup when your spelling is off if the project has a huge dictionary. This works the other way too—you’ll need less memory and have faster lookup if you leave out source or header files that are logically part of your project but for which you don’t need regular access or lookup. An EnterAct project can contain files from up to 6 disks. If your project files are split across several disks, you should have all the disks on–line (mounted) before updating your dictionary or doing a multi–file search. EnterAct tracks your disks by name, and many other applications do the same. Please ensure that all your disks have different names. If you ever find it necessary to move a considerable number of files from one folder or disk to another, the simplest way to deal with the change in any EnterAct project that refers to those files is to throw the project away and create an new one. If only a few files are moved, you can use Remove File followed by Add Files and then Update Dictionary afterwards to update your project. Creating a project Select New Project from the EnterAct menu at any time. When you start EnterAct by double–clicking on its icon, you’ll see the New Project dialog if you cancel the Open Project dialog during the startup. Since the the project will always be saved for you automatically, there’s no such thing as an “Untitled” project: you’ll have to give it a home on your disk before doing anything with it. Three panes—.c, .h, plain text Any files you add to your project whose names end in .c or .C will be placed in the left pane, which is reserved for source files. Header files (ending in .h or .H) will go in the middle pane, and any other TEXT files that you add will end up in the right pane. PICT’s will also be placed in the right pane. If you have special file extensions after a period, eg “.Proto”, that you would like to have treated as source or header files, see the “Custom file extensions” section a few pages on. In each pane, the files are sorted alphabetically by name. Since EnterAct is not a compiler, there’s no need to set up code segments. Add Files—the old–fashioned way The Add Files command will let you repeatedly add files (one at a time) to your project, until you cancel the dialog. The appropriate pane for each file will be chosen for you. The type of the file you add can be TEXT or PICT. Add Files—the fast way Select Add All In Folder. Open a folder that contains files to be added, and select one of them. When you click the Add button, that file and all other TEXT files in the folder will be added to your project. Files in sub–folders will not be added. This command will also repeat until you click the Cancel button. If the file you select is a PICT, it will be added, but other PICT’s in the folder will not automatically be added. In any case, all TEXT files will be added. As with Add Files, there’s no need to select a project pane beforehand. On the rare occasion, you may want all files in all subfolders to be added to your project as well: to have this happen, hold down all three of the <Shift>, <Option>, and <Command> keys while using your mouse to pick Add All In Folder (the key command won’t work). This special case can be interrupted with <Command><period>, in case you accidentally do it while at the root level of your 300 Meg drive.... Add Mac Headers The Add Mac Headers command will search the folder that contains EnterAct and all sub–folders for the file “Quickdraw.h”. Wherever it is found, all files in that folder will be added. If you have not placed your Macintosh #include files in accordance with THINK C’s installation instructions (HardDrive: THINK C: Mac #includes) you may see a message from EnterAct mentioning that “Quickdraw.h” wasn’t found anywhere. Add Standard C Headers The same as Add Mac Headers, except that all files in the folder containing “stdio.h” will be added to your project. This file is typically in HardDrive: THINK C: C Libraries: headers. Remove File To remove a file from a project, bring the project window to the front, select the file by clicking on it, and then select Remove File. If you have built a dictionary for the project, the dictionary will be automatically updated for you. There is no “Remove All Files In Folder” command, just the one–file–at–a–time Remove File, so if you accidentally add all the files in the wrong folder it will probably be quickest to just start over with a new project. This shouldn’t take long Custom file extensions The “File Extensions...” command under the EnterAct menu allows you to specify additional file extensions beyond the standard .c, .C, .h, and .H. Type in your own extensions (up to 6 extensions, each up to 5 characters), and pick which pane the file should be added to. For example to have “.Proto” files added to the middle pane type in “Proto” in one of the extension fields and click the corresponding “Mid pane” button. Extensions are case-sensitive, so “PROTO” is not the same as “Proto”. If you have multiple versions of the same extension, you should enter them separately. If a project is open when you pick “File Extensions...” the extensions you enter will apply to that project only, as indicated by the “This project” button. If no project is open at the time, the extensions will be used for any new project you create (the bottom-left button will read “New projects” in this case). PLEASE NOTE any file that is added to the left or middle panes will be parsed, and terms contained will be built into your dictionary. This means the files must be in C (or at least “C--”), otherwise the dictionary-builder will complain. Distinguishing ".h" from <.h> The ".h" and <.h> buttons in the Find dialog let you set up a multi–file search for just one kind of header (ie system or your own), and since bullets • are shown beside selected files selecting one or the other kind will give you an on–screen way of telling which are which. Note for this to work properly your system headers should be in the same folder as EnterAct itself, and your own headers should be in a folder outside the one that holds EnterAct and THINK C. Copy and search in the project window When you have a file name selected in the project window, you can Copy it and then Paste it into a text window. This helps sometimes with documentation. With the project window in front, pressing any key will scroll the current project pane to the first file name that begins with the single character you typed. This is something like a file open dialog, but responds to just one character at a time. And, if you have an enormous project, the Find dialog will let you search for part or all of a file name in a particular pane. Select the pane in the project window that you wish to search, call up the Find dialog, and then continue as though you were searching for something in a text document. Tips When you double–click on a file–name in the project window to open a file, the project window will at the same time move to the back behind all other windows. If the project window becomes hidden, you can bring it to the front again by selecting it from the Windows menu or using the menu key equivalent <Command><zero> which is always for the project window. Since the project window goes all the way front or back with a key–stroke or double–click, you can if you wish make the project window relatively large and treat it as a sort of backdrop mini–Finder. If you begin the names of your own header files with a common character or group of characters, they will end up grouped together in the middle pane of your project window. You shouldn’t add more than 16,000 files to one pane. You wouldn’t want to anyway, since EnterAct will start to bog down noticeably if you go beyond about 500 files total for all panes. However, if you’re patient and have enough RAM you can build an enormous project, and in the end lookup will still be instantaneous if your spelling of a term is exact. If your spelling is off, you’ll be “in for the long wait” as a friend of mine puts it, so it would be best to think of enormous projects as strictly for review and learning purposes (where you can click and <Enter> beside any term you see and be assured that lookup will be immediate) rather than for creating new code. ---------------------------------------------------------- Dictionaries ---------------------------------------------------------- Introduction Dictionaries contain entries for virtually everything in every .c or .h project file that is not restricted in scope to the body of a function, struct, or union. For functions and methods the dictionary entry will be the prototype or equivalent, and for all other terms the entry will consist of the entire statement in your source code in which the term was mentioned or defined. Regular use of Update Dictionary (or Update Dictionary From Disk) will keep your dictionary current as you develop your source code. What’s in a dictionary After you’ve built your dictionary with the Update Dictionary command (see the next section), it will contain entries for everything of interest in .c and .h files that you would want to use in more than one function. Specifically there will be an entry for every: function—all types including static, in–line, method struct, union, enum, class enum constant #define—constant and macro typedef variable—all types including static, low–memory —provided only that the term is defined or mentioned outside of a function, struct, or union body. Dictionary entries for functions and methods will contain the prototype or equivalent. For all other kinds of terms, the dictionary entry will consist of the complete C statement in which the term occurs in your source code. All variants of a particular term will be included as separate entries in the dictionary. For example, if your source code contains the definition of a function and also a prototype for the function, then two entries for the function will be made in the dictionary. You can view other entries by pressing <Enter> again after the lookup window appears—see the “Lookup” chapter for details. To make it into your dictionary, the term must be defined or mentioned outside of a function, struct, or union body. For example, if you place the definition of a struct inside a function body there will be no entry in your dictionary. Any terms inside the standard “#if 0 ... #endif” construction won’t be included in your dictionary. However, terms inside any other sort of conditional construction (such as “#ifdef SomeThing ... #endif”) will be included*. Building your dictionary After you’ve added all your files to your project, select Update Dictionary from the EnterAct menu. If the dictionary–builder stumbles over a statement that’s too mangled to parse, you’ll see a message explaining in general what the problem is. You’ll also see the file in question, with the cursor placed at the position where the error was detected. Generally, most problems reported will be well–localised and fairly easy to fix—typical problems are lack of balance for critical delimiters, and missing or very badly spelled keywords. If you don’t see what the problem is, consult the “Dictionary build problems” section of the last chapter, ”If there’s a problem”, and the “If there’s a problem” section at the end of this chapter. EnterAct’s dictionary–builder will properly interpret a great many first–draft errors, including missing semi–colons, lack of balance in some delimiters (these vary according to context), slightly misspelled keywords, and nearly all errors, except for certain delimiters, that occur within the bodies of function and struct, union, or class definitions. In other words, your code may be far from compilable and yet produce no complaints when EnterAct builds the dictionary. Yet, in a contrary sort of way, using EnterAct will almost certainly reduce your first–draft errors. This is simply because you now have instant access to all spellings and types of struct members, all function calls, etc, so a major source of errors is now gone. And the time you save by using EnterAct’s lookup and editing capabilities might be partly devoted to reviewing your code before submitting it to the compiler, once again using lookup to clarify details when needed. Keeping it up to date EnterAct does not update your dictionary automatically. Generally, you should select Update Dictionary whenever you change or add something that you’d like to have in the dictionary. Changes that take place entirely within the body of a function will not affect what’s in your dictionary. Any changes outside of a function body, including adding a new function, adding or changing an enum constant or struct or class member etc will be changes that you’d normally like to have reflected in your dictionary. Update Dictionary will rebuild the dictionary only for those files that have been changed since the last update. However, EnterAct will not be aware of any changes to files that you made using some other application. So, if you don’t recollect that all of the changes you made with some other application were entirely within function bodies, select Update Dictionary From Disk to bring your dictionary thoroughly up to date. Update For Front File Only will rebuild only that part of your dictionary that is determined by the front text window. Unlike the other two update commands, this is a “manual override”, and rebuilds the dictionary for the front file whether or not it needs rebuilding. Normally you won’t need to use this command, because a full update with Update Dictionary for all changed files is almost always very quick. In fact, off hand, I can’t think of any use for the Update For Front File Only command. But it’s there if you want it. How long will it take? Typically an update zips along at two to three files per second on a Mac II once it gets going—comparable more to multi–file search speed than compilation speed. There is a bit of overhead for an update, so an update for just one file may take for example three to four seconds in a project with a total of one Meg of source and header files. An update for six changed files in that size of project would take about six seconds. However, no conditional rebuilding is ever done, meaning that no matter which single file is changed, the dictionary–builder will reanalyse only that file and no others, even if it is the sort of header file that is #included everywhere. Selecting Update Dictionary From Disk rather than Update Dictionary will typically add no more than two seconds per 100 files to the total rebuild time. If you need to interrupt the dictionary update, press <Command><period>. This also interrupts multi–file searches, and printing, by the way. You can finish the job off properly later by reselecting your original dictionary update command. Show Dictionary This command just produces a “raw” dump of all the text in your dictionary, consisting of all the definitions or declarations that the dictionary–builder extracted from your code. You might find this command useful for extracting a list of “near–prototypes” for all of the functions in a file. The entries in the dictionary dump will be grouped together by file, and within each file will appear in the same order as they occurred in the original file. This typically means that the entries taken from the definitions of all functions in a file will be grouped together in a file. Find one with a search, and you’ve found them all. You’ll have to add semicolons (and rework the parameters if you use “old–style” function definitions), but you will be able to grab all the “near–prototypes” with a single Copy. If there’s a problem See also the “If there’s a problem” chapter, especially the “Dictionary build problems” section. If you run into an “Unbalanced comment” message, and you are one of those people who intentionally uses doubled comment starts, as in /*#define Humpty /*break no eggs if not defined */ you can get around this by selecting Options and unchecking the “Detect nested comment starts” option. Keep in mind though that this will partially disable EnterAct’s ability to trap comment errors. If the problem seems to involve a macro, see the last page of the “Not everthing goes” chapter for a discussion of the Macro's to skip command. The messages that EnterAct displays when it runs into a problem are moderately long, often with a suggestion as to how the problem might be fixed. Most errors encountered during dictionary updating that produce a message will either be very close to the position of the cursor in the file you are shown or will be due to lack of balance in some delimiter. If the problem seems to be lack of balance, the message will suggest that you try the Balance command immediately after OK’ing the alert message. In particular, EnterAct accurately detects all single failures to properly start or end a comment (unless you choose to ignore comment start errors as described on the preceding page). If the problem isn’t with balance, the error will usually be very close to the cursor, and will typically be a misspelling, or missing or wrong punctuation. In rare cases the error may be at the other end of the single statement where the cursor is, but that’s the worst case. Minor misspellings of some keywords won’t be a problem, but there is a limit: typdef sturct Something... is OK, but twerpdeaf stork is not. EnterAct does not detect all misspelled keywords, and will often tolerate a repeated keyword, but in those cases it won’t matter for the purpose of building a dictionary. EnterAct’s tolerance of errors complicates repairing multiple serious errors, since you may fix an error only to discover that EnterAct didn’t mind that one, and shows you the same error message again. Be consoled that any errors you do fix would have to be fixed anyway at compile time. Although it’s extremely unlikely that you’ll run into this, keep in mind that EnterAct cannot properly handle certain theoretically possible constructions, having to do mainly with #defined equivalents for important keywords and punctuation, and with the perverse misuse of round brackets. See “Not everything goes” for details. The method of second–last resort: take your files to THINK C and compile them. The method of last resort? 1-416-595-9440. ---------------------------------------------------------- Lookup ---------------------------------------------------------- Introduction With a bit of practice, you should find that the entry you want will be among the first three shown almost all of the time, no matter how shaky your memory is. The reason is that even in a very large project there are remarkably few names that are similar to one another—a credit to natural inventiveness when it comes to naming things, and a small blessing that EnterAct allows you to take advantage of. Almost every name that you or someone else creates will be distinctive in some way, and the distinctive part is the part that you’ll remember best. That’s all EnterAct needs. Completely automatic lookup is also available: select AutoLook, and put the AutoLook window somewhere handy. You’ll be surprised at how often it retrieves the information you want, just before you realise you need it! Click, press <Enter> To look up a term in your dictionary, either type it in or click just to the right of it and press <Enter>. If you supply an optional hint (see “Hints for speedup” below) you should press <Enter> with the insertion point just to the right of the one–character hint. A lookup window will appear showing the best dictionary entry that matches what you typed. If it is not the exact entry you wanted, press <Enter> again to see more entries When you have one or more characters selected in a lookup window, pressing <Enter> means “show me the next entry”. The total number of entries is shown on the right side of the display box at the window bottom, just after the number of the current entry you are viewing. Since a selection is made for you automatically whenever a new entry appears, pressing <Enter> repeatedly will take you through all available entries in the lookup window (and back to the first entry at the end). To view the previous rather than next entry, hold down the <Option> key while pressing <Enter>. The display box occupying part of the scroll bar space along the bottom of the lookup window will show you, from left to right: the file that the entry was taken from; a one–letter abbreviation indicating the type of entry (# for define, s for struct etc), and then the current entry and the total number of entries available in the lookup window. For a full list of the one–character abbreviations, see the “Hints for speedup” section below. Your spelling If your spelling exactly matches any term in your dictionary, you will be shown all entries that match exactly, up to a maximum of 60. They will be presented in no particular order. Since the dictionary builder records all variants, there may often be, for example, three different entries for a function—defining instance, prototype, and prototype with “extern” at the start. (Some people like to prototype a function without the “extern” at the top of the file where it is defined, so the list of prototypes there serves as a table of contents: and placing “extern” at the beginning of a prototype when it is being called in another file makes it obvious that the function is defined somewhere else.) EnterAct’s lookup is always case–sensitive. This is not optional, because C is always case–sensitive. If you’re just starting C, you’ll find good guidelines for capitalization at the start of the first volume of Inside Macintosh. If your spelling does not exactly match any term in your dictionary, you will be shown the entries that come closest. The number of entries in the lookup window is in this case up to you, as set by the “Number of entries per lookup window” option in the Options dialog. If you suspect in a particular case that your spelling might be way off, you might want to temporarily increase the number of entries kept to 10 or more to improve your chances of retrieving the one you want. Normally, the default setting of 4 entries per lookup is adequate, though you might prefer 3 or 5 on a regular basis. You can change this option at any time. There is no significant speed penalty for increasing the number of entries kept. Lookup retrieval when your spelling is exact is always immediate, whereas the time taken when your spelling is off will be typically a few seconds. This time varies on average directly with the size of your dictionary, although it can vary in particular cases. If lookup on average takes longer than you’re willing to wait, the simplest cure is to trim unneeded files from your project, thus reducing the size of your dictionary. Second–best is to speed up your Macintosh (plugging in to 600 volts will provide only a temporary speedup). Hints for speedup When you type in a name and press <Enter>, you know what “kind of thing” you want, but EnterAct doesn’t. Supplying EnterAct with a quick hint will help speed up the lookup if your spelling doesn’t match an entry, and it will in all cases limit the entries that are retrieved to the type that you specify with the hint. A hint for lookup consists of one character added after the name you wish looked up. Normally you’ll need to first type a space and then the one–character hint, to separate it from the name. However, the hint for a function “(” and the hint for a #define “#” can’t be part of any name, so you don’t need a space for these two. Here are the hints you can supply, with examples: in all cases you should select an insertion point just to the right of the hint just before pressing <Enter> so that EnterAct can pick up the hint correctly. For all except the function and #define hints, a bit of space (blanks or tabs) between the name and the hint is necessary. Type Hint Example function, method ( SomeFunc( struct, class s MyStruct s variable v globalVar7 v #define # BIGNUM# union u IntOrFloat u enum e ErrorCodes e enum constant c noMemory c typedef t MyStruct t In the display box of a lookup window you will see one of the above hints for each entry, between the file name and the current entry number. This is just to remind you that EnterAct keeps track of what kind of thing each term is, and that it will understand the above hints if you supply them. When should you supply a hint? Almost never. Perhaps when you have a struct, a typedef, and a variable that have very similar names, you don’t remember the exact spelling, and you want just one of them without the nuisance of the others. Since flipping through lookup entries is as fast as pressing the <Enter> key once the lookup appears, the only common reason to supply a hint is to speed up the lookup process itself. But in this case you should first try trimming unnecessary files from your project, as this will also speed things up by reducing the size of your dictionary. Number of lookup windows With too many lookup windows on–screen at once, your screen will be too cluttered. If too few are available, that will hamper you when you have a complicated problem to wrestle with. The upshot is that the maximum number of lookup windows on–screen at once must be under your control, so you can vary this number as the situation demands. You can change this number at any time by typing a new number in the “Number of lookup windows” box in the Options dialog. The default number is 4, but you can vary it from 1 to 10. The “Number of lookup windows” includes any that you mark for keeping around, and determines when a lookup window that is not marked for keeping around will quietly go away on its own. When you press <Enter> to see a new lookup and the lookup window limit has already been reached, one of the old lookup windows that was not marked for keeping around will quietly go away, and the new one will replace it. There’s no predicting which one, so if you want a lookup window to stay up until you explicitly close it, select Keep Lookup Around while it is the front window ( see “Keeping lookups around” below for details). Number of entries per lookup When your spelling doesn‘t match any term in your dictionary exactly, the number of entries that are retrieved in the lookup window is under your control. To change this number, select Options and type a new number in the “Number of entries per lookup window” box. The default of 4 suits most cases, but you may prefer 3 or 5. The maximum of 20 entries is useful only when your recollection of the correct spelling has gone right out the window. Keeping lookups around The command for this is under the Windows menu. When you select Keep Lookup Around with a lookup window in front, the lookup will be marked for keeping around. It won’t close unless you close it yourself. Other lookups not marked for keeping around may quietly close when you ask for a new lookup after having hit the limit of the number of lookup windows on–screen at one time. When you select Keep Lookup Around for a lookup window, the beginning of the window title will change from •• to ¶¶ to show you that it is marked for keeping. A ¶ is a Paragraph mark, which starts with P, and that stands for Permanent. A lookup window marked for keeping will close only if you select Close or Close All, or close the project, or leave EnterAct. AutoLook The AutoLook command calls up an automatic lookup window which updates by itself to show dictionary entries as you type, edit, or click around with the mouse. It shows only exact matches, and only one match at a time. Incessantly, with near–maniacal fervor, it will retrieve and display a definition for the word that lies just before your insertion point, or at the end of your current selection. For example, if there are entries in your current dictionary for “Window”, “WindowData”, and “WindowDataPtr”, then all three entries will appear in succesion in the AutoLook window as you type “WindowDataPtr”. Note that double–clicking on a word will produce results in the AutoLook window. Since the AutoLook window changes so often, if you want to preserve an entry you should look it up in the usual way, by clicking just to the right of the word (or partial word—it doesn’t matter what’s to the right of the insertion point) and pressing the <Enter> key. You can do the click–and–<Enter> in the AutoLook window if you wish. Paste Selection Behind This command is described briefly here because it is the easiest way to copy something from a lookup window and paste it into your working window. Details are in the next chapter, “Editing”. When you look up a function name, the function’s prototype or equivalent will appear in the lookup window with the function name and parameters preselected; at the same time, the function name that you typed in your working window will be selected (shown with a thick outline since it is not the front window). To paste a “template” for the function call into your working window, select Paste Selection Behind. This command will Copy what’s selected in the lookup window, switch to your working window, and Paste over what is selected there. Paste Selection Behind is also handy when you’re working with a struct and would like to paste in member names instead of retyping them. Call up a lookup window for the struct, and mark it for keeping around (see just above). Then, when you need a member name in your working window; switch to the lookup, select the member name, and Paste Selection Behind. That will return you to your working window with the member name pasted in. For non–functions, the lookup window appears with the matching term selected, and the term you typed in your working window is also automatically selected (this includes any hint you might have added). So correcting the spelling of a term is a matter of; press <Enter>, and when the lookup appears Paste Selection Behind. If the first entry you see in the lookup window is not the one you wanted, press <Enter> until you see the one you want. Editing an entry is temporary If you edit a lookup entry, you will lose your changes if you cycle to another entry in the same lookup window. The only way to permanently change a dictionary entry is to alter the corresponding source code statement (the display box in the lookup window will show you which file the entry was taken from). If there’s a problem In the rare case that your dictionary is small and the name you type doesn’t match any term in the dictionary to any reasonable extent, you’ll just hear a beep and no lookup will appear. The hint for #defined macros is the same as the hint for other #defines—add a '#' after the name, rather than a '('. In general, if the lookup you see is not what you wanted and you supplied a one–character hint, try again without the hint. Looking up classes and methods is discussed in the next chapter, “Browsing”. If you suspect your spelling may be way off, try increasing the “Number of entries per lookup window” in the Options dialog to 10 or more, and then try the lookup again. If you’re quite sure that a term should be in your dictionary but it doesn’t appear when you look it up, take a look at the statement where the term is defined or mentioned: you could have accidentally violated a required coding convention, or you could have a succession of first–draft errors that has confused EnterAct. A missing semicolon or misspelled keyword can result in a term being skipped. If you employ macro’s to do such things as optionally include or omit full prototypes, or typedef’s, then you should register them with EnterAct using the Macro's to skip command, as described in the “Not everything goes” chapter. If you run into a problem that stumps you, please compile your code in THINK C before calling for help. However, if you end up fixing bugs in your code that you feel EnterAct should have been able to tolerate, please call and complain. ---------------------------------------------------------- Browsing ---------------------------------------------------------- The Browse command The window produced by this command shows a “family tree” of the classes in your project, as of your last dictionary update, and also allows you to quickly view any class or method definition. It will close when you close your project, and will update automatically when you update your project dictionary. To view the definition of a class, double–click on the class name. This works much like <Option>double-click or Find Definition in a text window. To view a method definition, click and hold on the owning class name: after a brief pause (your double–click time, actually) a popup menu will appear listing all of the class’s methods. You should then select the method you want and release the mouse button, as if you hadn’t guessed. Classes without proper parents (orphans, if you like) will always appear in the left–most column of your browser window. A quick look down the left column will reveal whether you have any unintentional orphans, perhaps due to misspelling the parent class name in the class definition. Quite often, “CObject” is the only orphan you’ll have, but all classes declared to be “direct” or “indirect” and hence not a subclass of any other class will also appear in the left column. Browsing classes without the browser Nothing new to seeing class definitions—click to the right of the class name and press <Enter>. You will typically find the class name of an object as the first name in the statement where it is defined, as in className *objectName; You can also, of course, look up a class by typing the name and pressing <Enter>, and in all cases your spelling just needs to be reasonably close, not exact. To view the definition of a class when looking at one of the classes’ methods, see the section below. Browsing methods without the browser Method browsing is a bit trickier, since if you have something like currentObject->Draw(); and there are several different classes with Draw() methods, then EnterAct does not know specifically which Draw() method you want. If there is only one method in your project with a given name, then the lookup window will contain just one entry, but if there are several then the lookup window will contain all of them (up to a maximum of 60). For example, if you were to press <Enter> with an insertion point to the right of Draw above, then the lookup window might contain entries for void Circle::Draw(), void Square:: Draw(), void Oval::Draw() and so on. When there are several entries like this, you can cycle through them by pressing the <Enter> key, and back up by pressing <Option><Enter>. There are some illustrations of this two pages ahead. This raises the question of how to find where a method is defined. The general approach is described later in “Seeing where a term is defined”, but the approach for a method has one extra step: • first, look up the method and cycle through the lookup window until you find the method you want, based on the name of the owning class • then select the entire name, consisting of the owning class name, the two colons, and the method name, in general className::methodName •and then select Find Definition. Well, there is one exception to this: if there is only one method in your project with the name in question, then a standard <Option> double–click on just the method name will jump you to the file where that method is defined. However, if there are several methods with the same name in different classes, there’s no predicting which definition you will see if you just <Option> double–click on the method name—best to look up the method first, and use Find Definition on the full name of the exact one you want. By the way, when viewing the full “className:: methodName” of a method, you can look up the definition of the owning class of the method by clicking at the right end of the class name, before the colons, and pressing <Enter>. If the instance of the method name you’re vewing doesn’t have the class name attached, look up the method name as decribed just above to see the full method name including the owning class, and then do your lookup for the class in the lookup window shown for the method. If you want to see where a method is defined, but can’t remember the exact spelling of the name, type your best guess and press <Enter>. The true name you wanted will probably be among the first few entries in the lookup window, and then you can proceed with an <Option> double–click or Find Definition right in the lookup window to get to the file you want to see. If you want lookup for a method when you’re not sure of the spelling, and want to restrict the lookup to just methods, type a bit of the class name and two colons just before the method name—even C::method will do (even if the class name doesn’t contain a “C”—it’s the two colons which signal that a method is wanted). EnterAct is not a fancy bells–and–whistles browser, but it does allow you to look everything up quickly. And, it has two advantages over any other browser: your code doesn’t have to be perfectly compilable, just reasonably close; and your spelling when you want lookup for anything (including methods and classes) doesn’t have to be perfect, just close enough to be distinctive. Try that on your SmallTalk! (nice pictures here in the printed manual) ---------------------------------------------------------- Editing ---------------------------------------------------------- Introduction Everything that changes a document is undoable one way or another, except Replace All and Revert. The indentation of your code will commonly be preserved when you Paste. Paste Selection Behind combines Copy, switch to the next window, and Paste in one command. The selection in the next–to–front window is shown outlined to help in using this command. Reformat Selection can “pretty up” a comment or selection of text. Holding down the <Option> key while pressing the up or down arrow takes you to the top or bottom of your document. The rest is routine. The usual stuff Paste Selection Behind and Reformat Selection are new editing commands. Balance has its own chapter following this one. All other editing operations will be familiar if you’ve used THINK C. Paste has been enhanced to preserve your relative indentation. Undo EnterAct has one level of undo and redo, so if you decide to undo a change to your document you should do so before carrying out the next change. The undoable and redoable actions are: typing, Cut, Copy, Paste, Paste Selection Behind, Clear (Backspace), Shift Left, Shift Right, Reformat Selection, Replace, and Replace and Find Again. Replace All and Revert are not undoable. All other “undoable” changes (such as changing the font) can be undone by reusing the same command (such as changing the font back). To effectively make Replace All undoable, Save your document just before the Replace All. If you don’t want to keep the results, choose Revert to restore your document to the way it was before the replacement. Just clicking the mouse or selecting a range of text does not affect undo. Changing the window does make the last change temporarily undoable, but you can restore the ability to undo the last change by bringing the appropriate window to the front again. Typing, Cut, Copy, Clear “Typing” means hitting a sequence of keys that produces text, intermingled with any number of <Backspace>s. A new typing operation begins whenever you change the insertion point or select characters and then type something. As with all actions, just changing the insertion point or selecting characters does not affect your ability to undo—it’s the subsequent change to your text that does it. When you type <Return> the resulting new line will have the same indentation as the line above it, unless you hold down the <Option> key, in which case you’ll end up flush at the left margin. Clear has the same effect as the <Clear> key, and <Backspace> is also the equivalent of a Clear if a range of text is selected. If no text is selected, <Backspace> will delete one character, whereas Clear will not. Paste preserves indentation At least, it does if the range of text you select to be pasted over, or the insertion point for the paste, satisfies the requirement: “all tabs or spaces to the left at the start”. This means that the first character you select for replacement should be the first character on the line that is not a space or tab. If you have just an insertion point for the Paste, then the same applies—there should be nothing but spaces and tabs from the insertion point to the left margin. Starting at the left margin will also do. The basic rule is you shouldn’t “see” any printing characters between the left margin and the start of your selection or insertion point. If this rule is satisfied when you are about to Paste, then the paste will preserve your relative indentation, removing the need to Shift Left or Shift Right afterwards. About the only special action you should take to have Paste preserve your indentation is to open up a new line with a <Return> just before you paste in a block of code, which you probably do anyway. Paste Selection Behind also preserves indentation. One of the more obvious novelties of EnterAct is that it shows you what you have selected in the text window that is just behind the front window. This helps you to make use of the Paste Selection Behind command, and also shows you where you are when the Find dialog is in front of your text window. The selection in your front window is shown in the standard way, namely white text in a black box. EnterAct draws a thick black outline around the selection in your next–to–front window so you can distinguish it from the front selection. You’ll see the selection in your next–to–front window only when something can be done with it (such as Paste Selection Behind, or Replace). Paste Selection Behind This one is really great, entertains the kids for hours. Paste Selection Behind does the following three actions in one : Copy what is selected in the front window; switch to the window just behind it; and Paste the copy in over the selection in that window. You’ll see your selection in the next–to–front window just beforehand, as described above. If you can’t see what is selected in the next–to–front window, you can either trust to memory (it’s undoable) or do a “manual” Copy, switch windows, Paste. Paste Selection Behind is especially handy when switching back and forth between your working text window and a lookup window, but it can be used with any two text windows. Your indentation will be preserved with Paste Selection Behind under the same circumstances that apply to a Paste (see “Paste preserves indentation” above). If you want to undo a Paste Selection Behind but have switched to a different window, bring the two windows involved in the Paste Selection Behind to the front alternately until Undo becomes enabled. The two windows involved are the one you pasted into, and the one you copied from. Font, font size, tabs Sizes for your font are restricted to sizes that are actually installed in your system. The default font for text windows in EnterAct is Monaco 9, with 4 spaces per tab. You can also change the font for the project window. The default here is also Monaco 9. For projects only, holding down the <Option> key while changing the font or size will give you a bold style. Tabs in EnterAct are of the relative sort, meaning that when you press <Tab> your insertion point advances to the next tab stop. Tab stops are placed a fixed number of spaces apart, and you can change this number with the Tabs dialog. Note that if you change the font it may throw off your nicely–aligned code, so it’s best to pick one font for code at the beginning of your programming career and stick with it. Shift Left / Right Shift Left and Shift Right will shift one or more entire lines left or right by a tab stop, allowing you to repair or alter the relative indentation of your code or text. For simplicity, you should select one or more entire lines before calling these commands. They are undoable. Reformat Selection This command has a very high entertainment/utility ratio. In other words, even if you never need it you’ll enjoy playing with it. Reformat Selection will rebreak the lines in your selection, but the result may not always be an improvement. It is designed to work with multiple paragraphs, provided you don’t indent the beginning of the first line, and that you separate paragraphs with a blank line. Reformat Selection doesn’t work well on C code, although it may on occasion help to tidy up a complicated “if” statement. It works best with one or more paragraphs of text, either an entire comment or part of a comment, or paragraphs in a text document. Since Reformat Selection is undoable there’s no harm in trying it. The maximum selection that can be reformatted at one time is roughly the standard Text Edit limit, 32,000 or so characters. The specific reformatting that Reformat Selection does is governed by two options in the Options dialog. The default action is to rebreak lines with a “ragged right” format and a maximum line length of 74 characters, a nice width for printing Monaco 9. In the Options dialog (near the bottom) you can alter the maximum number of characters per line, and also select a “full justification” look if you want to knock people over with your comments. The maximum number of characters per line is restricted to a range of 30 to 150. Arrow keys for moving around The up down left right arrow keys will move your cursor by one character or line. If you hold down the <Option> or <Command> key an arrow key will take you all the way in the appropriate direction. <Option><up arrow> and <Option><down arrow> are especially useful for taking you to the top or bottom of your document. Go to The Go to Top and Go to Bottom menu commands do the same thing as <Option><up arrow> and <Option><down arrow>, namely take you to the top or bottom of your document. The Go to ... command is a cross between “go to line number...” and “open selection”. If you don’t have a file name or line number selected in your front text window, Go to... will present you with a dialog in which to enter a line number to jump to. If you select a file name in your front window beforehand, Go to... will open the file by that name, provided only that it is in your project. If you select a file name followed by a line number, as in “FilesAndResources.c 400”, you will go to that file and line number. File name extension such as “.c” or “.Notes” need not be selected, so if the main part of the file name is a single word with no spaces you can just double–click on it before selecting Go to.... If your selection beforehand is not a pure number, and the text before the number is not a file name, then you will be presented with the line number dialog—that is, arbitrary selections will in most cases not fool EnterAct into jumping to a line before asking you which line you want. If there’s a problem EnterAct has a single level of undo, and the window that the undo applies to must be in front in order for the Undo command to be enabled. To undo a Paste Selection Behind, the window pasted into must be in front, and the window copied from must be just beneath, the way EnterAct leaves them after carrying out the command. If you can remember which two windows were involved in the Paste Selection Behind, just bring them to the front alternately until the Undo is enabled. If Paste doesn’t preserve your indentation, it’s because you’re leaving some text at the left of the first line unselected when you select a range or insertion point for the Paste. In particular, Paste won’t preserve indentation if you select an insertion point for the Paste that is to the right of the first visible character on the line (“visible character” here meaning something that is not a space or tab). While we’re on the subject, you can switch off the preservation of indentation for a Paste by typing a single character just before you Paste, and then deleting it after the Paste. ---------------------------------------------------------- Balance ---------------------------------------------------------- Checks everything ...except those angular brackets that you find only in #include <SystemHeader.h>. The full list is (), [], {}, /* */, " ", and ' '. Balance will also detect nested comments and any single improperly–formed comment start or end. Two improper comment delimiters in a row (improper start followed by improper end, or vice versa) will not be detected, but that’s a one–in–a–million case that you’ll probably never see. Because Balance detects nested comments, it will signal an error if you use a comment start or end within a comment (nested comment starts are excepted if you deselect the “Detect nested comment starts” option)—see “Nested and bad comments” below. For strings in double quotes " ", the line continuation character '\' must be the last character on the line if the string is continued to the next line: "This string is \<Return> properly continued." "This string will trigger<Return> a Balance error." "So will \<space><Return> this string, due to the space before Return." Balance will behave in different ways depending on where you are in the code. To Balance an entire file, select an insertion point at the very top of the file (<Option><up arrow> will take you there). To Balance a specific delimiter, either click just to the left of it or select the delimiter (note for comment starts and ends this means both characters). Given an insertion point, Balance will first look to the immediate right for a delimiter that wants balancing, and then to the immediate left. When several delimiters are side by side, you can avoid having to remember this by just selecting the delimiter you wish balanced. Clicking between the characters of a comment start or end also counts as a “hint” to find the other end. If your range of characters selected doesn’t consist of just a single delimiter, or if your insertion point is not right next to a delimiter, then Balance will try to find the smallest enclosing pair of delimiters. Your selection range will expand to the next enclosing pair as you repeat the Balance command. Shows the error location Any unmatched or mismatched delimiter will be selected and shown. In the case of mismatched delimiters, you can switch between the two delimiters by selecting Balance again. If the delimiter is an “orphan”, the second Balance will just produce a beep, since there’s no other end to show. Balancing a file Given an insertion point at the top of a file, Balance will balance the entire file. If you hear a beep and the cursor does not move from the top of the file, that means the entire file is balanced. Either Go Top or <Option><up arrow> will take you to the top of a file. Balancing a file by starting from the top will always work correctly. You can also Balance a file by starting at the very bottom, but this may not work properly if the file contains any assembly–language sections (see “The asm problem” at the end of this chapter). Balancing a specific delimiter Balance looks for a “hint” from you, as indicated by your insertion point or selection, before going ahead. As mentioned above, you can Balance one specific delimiter by selecting it just before the balance, or by selecting an insertion point just to the left of it. If the delimiter is not next to another delimiter, you can click on either side of it. With comments and strings it is best to start the Balance off with a “hint”, that is, select one end of the comment or string or click next to one end, since if you start in the middle of a comment or string the text will be checked as strictly as possible, without allowance for it being within a comment or string. Nested and bad comments Balance will detect all nested comments, and any comment that has one end missing. In the case of a comment with one end missing , you will be shown a “good” end in the vicinity of the bad one, and you’ll have to deduce on your own where the other end should be. Comment errors can sometimes be subtle and difficult to see, such as a space between the '*' and the '/'. You may find it worthwhile to Balance all your source files with EnterAct’s balance command, since comment errors can sometimes slip past THINK C’s compiler, resulting in some of your code being quietly treated as though it was commented out. This can have unpleasant consequences—if you’re not lucky, it can generate a wild pointer. Note that any files in your EnterAct project are guaranteed to be free of these comment errors after a successful Update Dictionary, since the dictionary–builder checks comments thoroughly. The one price to be paid for EnterAct’s improved comment checking is that you should not use a comment start or end within a comment. Such things as /*.../*...*/ and /*...*/...*/ will be treated as errors, both by the Balance command and by the dictionary–builder. If you do need to use a comment start or end within a comment, the general cure is to place some character between the star and the slash. A space will do, or you could be pedantic and place each character in separate single quotes, for example instead of /* use / * or '/''*'. Well, OK—some of you deliberately double up your comment starts to save on typing. If you do this, select the Options command under the Edit menu and uncheck the “Detect nested comment starts” check box. This affects the dictionary builder also. Starting in the middle If your selection doesn’t indicate a hint, Balance first looks backwards in your file for a delimiter; when it finds one, it then looks forwards for another delimiter, hoping to match them up. Of course, if you supply an opening delimiter as a “hint”, or start from the top of the file, Balance will proceed in the forward direction immediately. On rare occasions you may wish to balance the contents of a comment or string as though it were code, and not just text. To do this, click or select a range of characters within the comment or string, away from either end. Balance will then check all delimiters as it works outwards, until it encounters one end of the comment or string and “realizes” that it has been fooled. By the way, EnterAct also accepts “C++” style comments, as in //comment beginning with two slashes, to end of line but only to the extent of skipping over the contents when balancing. If you start the Balance within this sort of comment it will be treated as code rather than text, just as with ordinary comments. Diagnosing a problem When you Balance an entire file, you will hear a beep whether or not the file balanced, just to tell you that the balancing is finished. If the cursor doesn’t move from the top of the file, that means the entire file is balanced. If there is any error in the file, you will be shown the first unbalanced delimiter. When balancing just part of a file, you will hear a beep only if there is an error. Otherwise, the selection range will quietly expand to the next largest balanced range. If there is no larger enclosing range (this is the case when you start with an entire function body selected, for example) you’ll hear a beep but the selection range will not change. With the exception of strings, only two types of balance errors can occur; mismatched ends, and missing ends. If Balance beeps and shows you an unbalanced delimiter, try immediately selecting Balance again. Then, if the problem is due to mismatched delimiters, you will be shown the other end. If the problem is a missing end, nothing new will happen—you’ll hear another beep, but the selected delimiter will not change. Strings in double quotes " " are checked for one additional special error, a missing backslash if the string is continued across lines. The backslash must be the very last character on the continued line, just before the <Return>—note that even a space before the <Return> will “hide” the backslash. Personally, I don’t think this is reasonable, but that’s the way C is. The asm problem If Balance runs into an “asm {...}” construction while looking backwards through your code, it just plain won’t know that it’s inside an asm. Any error you’re shown in this one circumstance is not to be trusted, since it will almost certainly be due to a delimiter inside an assembly–language comment (they start with a semicolon). When you balance a file from the top, all asm constructions will be handled properly. The dictionary–builder, by the way, also handles asm’s properly. Be warned that in other cases if you ask Balance to run backwards through a block of assembly language it will hiccup if it runs into a delimiter within an assembly–language comment. This is a bug, but I haven’t found a cure that wouldn’t slow balancing down to a crawl. Because of this problem it is best to always balance an entire file by starting from the top rather than from the bottom, unless you’re sure that the file contains no assembly–language. To Balance an assembly–language block, or a function containing assembly–language, select or click next to the opening curly brace '{' at the top rather than the closing curly brace. Otherwise, this will only be a problem if you’re balancing inside a function that contains a block of assembly–language. Then, you should select opening delimiters rather than closing delimiters before balancing. ---------------------------------------------------------- Search ---------------------------------------------------------- Introduction Single and multi–file searches in EnterAct are controlled by a modeless Find dialog. The one important novelty is that you fine–tune your multi–file selection by holding down the <Option> key and dragging over the files in the project window (bullets • appear beside each file included in the search). Replace, Replace and Find Again, and Replace All are all undoable. Find is modeless This requires a few minor adjustments in the way you search. There is no Cancel button in the Find dialog box—it has a Close box instead. While the Find dialog is the front window, search commands that deal with single files will apply to the window just beneath the Find dialog. Replace All is excepted because it can cause multiple changes, so to use this command you must have the text window in front. The “Find” button is the equivalent of the Find Again command. When you click the Find button or select Find Again, the window just beneath the Find dialog will be brought to the front, and the next instance of your find string shown. The Find dialog will stay on–screen, moving just behind the window being searched, so to find again you can if you wish leave your mouse stationed over the Find button and double–click (not a true double–click, the first click brings the Find dialog to the front, and the second does the Find Again). Buttons for multi–file searching are incorporated directly in the Find dialog. To modify your multi–file search selection of files, hold down the <Option> key and drag over the file names in the project window. You’ll see the “eyeball” cursor while doing this. Find options Select “Match Words” if you don’t wish to match a longer string that contains your find string in a form that makes a different word. For example, the string “Open” will also match “Opening”, “Opened” etc unless you select the “Match Words” option in the Find dialog. A special case: if your string begins or ends with puncuation, such as “->structMember” then leave “Match Words” unselected. “Wrap Around” will continue your search from the beginning of your document if the next Find runs off the bottom end of it. This also affects the Replace commands: to Replace All instances in a file, it’s simplest to select an insertion point at the top of the file beforehand; to Replace All instances below a certain point, click just before the position where you want the replacing to start, and leave “Wrap Around” deselected. “Ignore Case” treats upper and lower–case letters as the same. <Tab> and <Return> A plain <Tab> will jump your cursor from one edit field to the other, and a plain <Return> is the equivalent of the “Find” button. To enter a <Tab> or <Return> in either the find or the replace text, hold down the <Command> key while typing the character. Find again This menu command is the equivalent of the “Find” button in the Find dialog, and finds the next instance of your find string in accordance with your Find options (see above). Find Again searches the front window, or, if the Find dialog is in front, the window just behind the Find dialog. Enter selection Enter Selection will replace your current find string with whatever text you have selected. It works with any text window including lookup windows, and also the project window (in case you wish to search for a file name). If your Find dialog is on–screen, you will see the new find string in the dialog. Recent finds are remembered Your most–recent find strings will be stored in the popup “Find:” menu at top–left of the Find dialog. Selecting an item from the popup will copy it to your find string box. Two minor limitations apply: find strings containing <Return>s or more than 48 characters will not be remembered by the popup menu. Replace Replace can be thought of as a Paste for short strings (up to 255 characters). The replacement text is taken from the replace string in the Find dialog. No checking is done to see if the selection that will be replaced corresponds to your find string, so the replacement string can in effect be used as a second (small) clipboard. To set up a choice between two “Paste” alternatives, enter one selection into the replacement string in the Find dialog, and then Copy the other selection. Then Paste or Replace in your document as appropriate. If the Find dialog is in front, Replace will affect the window just behind the Find dialog. Replace is undoable provided the window in which the Replace was done is in front, and provided you don’t perform some other undoable action before undoing. Replace and Find Again This command is the exact equivalent of Replace followed by Find Again, and is undoable. Replace All Unlike other search commands, Replace All cannot be called when the Find dialog is in front—you must specifically bring frontmost the window in which you wish to use Replace All. This small awkwardness is an attempt to remind you that Replace All is the one editing command that can make a real mess of your document. However, it is undoable—as with other undoable operations, you need only have the correct window in front before undoing. If you have selected the “Wrap Around” option in the Find dialog, Replace All will indeed replace all instances of the find string with the replace string throughout your document. If “Wrap Around” is not checked, replacement will be done only below your current position in the text. To prevent a single instance of the find pattern from being replaced, select at least the first character of the instance in your document just before Replace All (selecting all of it will do). Multi–file searches Any file in your project can be added to a list of files to be searched. Files that are included in a multi–file search will have a bullet • just to the left of the name in the project window. “Coarse” setup of the multi–file search is done with the small buttons in the lower–right of the Find dialog. These allow you to select all files of a particular type—.c, ".h", <.h>, or plain text. The “None” button will clear the multi–file search selection, and the “All” button will add all of your project text files to the list. A counter in the Find dialog shows how many files will be searched. To “fine–tune” your list of files to be searched, hold down the <Option> key and click on or drag over the files in the project window. The cursor will change to an eye, and bullets beside the file names will appear or disappear as you drag up and down over the files. There is an illustration of this near the beginning of this chapter. Once your files are selected (and you’ve entered what you want found in the find string in the Find dialog) select Find In Next File or click the equivalent button in the Find dialog. As the search progresses, you will see the bullets beside file names in the project window disappear as each file is searched. The counter in the Find dialog will also count down the number of files remaining. If an open file is searched by Find In Next File, it will be searched from the beginning of the file. When an instance is found, Find Again will locate other instances in the same file. To continue the multi–file search with the next file, select Find In Next File again.When all files have been searched, you’ll hear a beep, the counter in the Find dialog will read zero, and all bullets will be gone from the project window. Even if you don’t find anything, it puts on a nice show. A <Command><period> will interrupt a multi–file search, and also clear the list of files to be searched. Markers and Automark A “marker” is a marked location in your text consisting of a start point, an end point, and a name to be associated with the marked position. To place a marker, select either an insertion point or the range of text that you want remembered, and then select the Mark command. You will be asked to supply a name for the marker: click OK, and then forever after you will be able to jump to that marker whenever you want (marks are saved to disk and properly maintained). To jump to a marker, hold down either the <Option> or <Command> key or both and click-and-hold in the title bar of your window. You’ll see a popup menu listing all of the markers attached to your file. Pick one, and you go there. The markers are in alphabetical order. Markers do stay attached to the proper position as you edit the file around them, but any editing that’s done inside the marked range will correspondingly expand or shrink the range associated with the marker. If you remove all of the text that is within the marked range, you will also remove the marker, and this is not undoable. Markers do not survive cutting or pasting—they stay attached to the text only as long as the text remains in the document. To remove one or more markers, select Unmark. You will be presented with a list of markers to select for deletion. This list follows the standard Macintosh rules for list selection: click with no keys held down to select a single marker (this deselects any other selected markers); click with the <Shift> key down to select a contiguous range of markers while dragging the mouse; and click with the <Command> key held down to select a marker that is away from other selected markers (the markers in between are left unselected). Mind you, adding markers to a file for the first time can be tedious. So pick Automark from the “Search” menu instead, and let EnterAct do the work: This command works with any C file, whether or not it has been added to your project. If you wish to keep special markers that you have manually added, leave “Clear all present markers first” without a check mark. When a duplicate name or position is found while adding markers, the new entry will replace the old one. The “first of group only” checks have slightly different interpretations: for #defines, it means mark only the first of a group of consecutive #defines; for enum constants, it means mark only the first within an enum {} statement; and for variables it means mark the first of a group of consecutive variables, whether they occur in the same statement or in separate statements. If you leave some types unselected then EnterAct’s automarker won’t count them as separating, say, two groups of variables or #defines. To keep things sane, there is a limit of 499 marks to a file. This is a 9 foot popup menu, a bit tedious to scroll through even with a 68050. Marker names are limited to 63 characters, but the range of text you mark with the name can be as long as you want. PLEASE NOTE your markers will be maintained properly only by editors that implement MPW–compatible marks. In particular, if you edit a marked file with THINK C version 4 or earlier, your marks will be thrown off. However, if you use Automark to set all of your marks, then re–marking a file after editing it with such an editor will be relatively painless—just use Automark again with your preferred options checked, and check “Clear all present markers first”. ---------------------------------------------------------- Documents and windows ---------------------------------------------------------- New, Open, Close New under the File menu means a new text window. To create a project, select New Project from the EnterAct menu. A new lookup window appears automatically whenever you look something up. New PICT windows can’t be had, no matter what you try. Open under the file menu allows you to open any TEXT or PICT document. To open a project, select Open Project from the EnterAct menu. Close will close the front window, whatever it is, and the key equivalent <Command><J> is often handy. Close Project will close the project window whether it is in front or not. Only one project can be open at a time, so if you select Open Project while a project is open you will be asked to confirm putting away the current project. The same applies if you select New Project. To close all text windows, select Close All from the Windows menu. This will not close your project or the Find dialog. Save, Save As, Revert Save applies only to proper text documents (not lookup windows) and to PICT’s. Saving a PICT will alter only the window location that EnterAct saves with any file. To save the contents of a lookup window, Copy what you want and Paste it into a regular text window. Projects are saved automatically, when you update the dictionary, add files, or close the project. Save As can be used with text and PICT documents, and with a project as well. In particular, you can set up a project to use as “stationery”, with the font and window location preset, and commonly needed files already added. Revert applies to text and PICT documents only. Saving window locations Saving window locations is nice, provided you aren’t pestered all the time to save your changed location when you close a window. In EnterAct, saving window locations takes the place of neatly tiling and stacking windows. By default, EnterAct will save window locations whenever you save a text or PICT document. If you would rather not have window locations saved, call up the Options dialog and uncheck the “Save document window locations” item. Any saved locations will also be ignored when a document is opened if you uncheck this item. ... without being pestered Beneath the “Save document window locations” item in the Options dialog there’s another check box, “...but don’t pester me about saving locations”. Both of these options are on by default. The “don’t pester” part means that you will not be asked if you wish to save a text window when you close it if all you’ve done is change the window’s location on the screen. The location of the project window is always saved (this is automatic) regardless of your options. Newly opened windows can be long or short If the “Save document window locations” item in the Options dialog has a check mark, and if a document you open has a window location saved with it, then EnterAct will restore your document to its saved location. Otherwise, EnterAct won’t have a remembered location for the window, or will ignore it (this is especially true of a new text window). You can roughly control the length of these windows with the radio button options “Windows open short / long by default” in the Options dialog. Long windows will reach all the way to the bottom of your main screen when they open. Short windows will indeed be relatively short on a large screen, but will fill most of a small screen. The default is short windows. Note that you can grow just the length of any text window down to the bottom of the screen by holding down the <Option> key while clicking in the zoom box. The default width of a window is fixed at a moderate size, about 74 characters in Monaco 9. This is also a near–maximum nice width for printing. If you ever wish to reset a window to this nice–for–printing width: Save your document; uncheck the “Save document window locations” item in the Options dialog; alter your document by typing something; and then Revert the document to the saved form. OK, OK, this is a kludge, but it’s better than nothing. <Option>–Zoom zooms just the length If you hold down the <Option> key while clicking in the zoom box of a window, only the length will be affected. If you’re zooming out (the first zoom is usually an “out”), the bottom of the window will drop down to the bottom of your screen, rather in the way a menu drops down. Zooming in is not affected by the <Option> key. (Tech Note: the length will actually grow to the bottom of the shortest screen that the window touches. Much gray hair here until I tried the “cookie–cutter” approach: get the gray region, and stamp alternate window sizes out of it using SectRgn or UnionRgn.) Number of windows at one time EnterAct has fixed limits on the maximum number of windows on–screen at one time, as follows: regular text 20 lookup 10 PICT 4 project 1. If you find any of these limits (except the project limit) restrictive, please let me know. There is one circumstance in which the text window limit does not apply: you can print any number of EnterAct text files by selecting them in the Finder and then selecting the Finder’s print command. While the hard upper limit on lookup windows is 10, you can set the maximum number on–screen to any number between 1 and 10 using the Options dialog. The default number is 4. The Windows menu Consisting of: Close All, Save All, Keep Lookup Around, and “bring a window to the front”. Close All affects text, lookup, and PICT windows. If it needs saving, you’ll be asked. Lookup windows will be quietly closed, since they cannot be saved. The combination of Close All with remembered window locations lets you arrange groups of documents to work with at one time, and switch between groups with a minimum of nuisance. Save All will save any text or PICT documents that need it (note lookup windows aren’t saveable). If a text window hasn’t been saved yet, you’ll see the standard Save As dialog. If you use MultiFinder, and you decide to switch off the “Safe switching under MultiFinder” option in the Options dialog, I would strongly recommend that you use Save All or preferably Close All before switching to another application. Keep Lookup Around applies only to lookup windows. The maximum number of lookup windows on–screen is fixed (although you can change this number at any time in the Options dialog), and when this limit is reached the next lookup window that you call up will quietly close one of the old lookup windows to make room. To avoid having a particular lookup window disappear later on you, select Keep Lookup Around when the lookup window is in front. The two bullets •• at the beginning of the lookup window’s title will change to ¶¶, showing that it won’t go away until you yourself close it. Note especially that Close All will close all lookup windows, whether or not they are marked for keeping. To bring a window to the front, select it by name from the lower part of the Windows menu. If a project is open, it can always be brought to the front with the menu key–equivalent <Command><zero>, which is worth memorising. No other windows (except dialogs) have key equivalents—if your memory is that good then in my humble opinion you don’t need EnterAct in the first place. The display box All text windows including lookup windows have a small “display box” along the bottom in the horizontal scroll bar area. For a regular text file this displays the name of the file; in a lookup window it shows the name of the file from which the entry was taken, followed by the (abbreviated) type of entry, the number of the current entry shown, and the total number of entries available in the lookup window. When you drag the mouse to select text in a text window, the display box will change to show the line number that the mouse is currently on, followed by the number of characters selected. If more than one line is selected, the display box will show the number of lines selected rather than the current line number. To determine how many lines there are in a file, use <Option><down arrow> or Go Bottom and click on the last line of the file. To determine the number of characters in a file, click at one end of the file and then <Shift>click at the other end of the file. Printing To print a text file, bring its window to the front and select Print. A Page Setup beforehand will be needed if you wish to print in a nonstandard way, such as sideways or with an unusual paper size. To stop a printout, press <Command><period>. Printing of PICT’s or other kinds of files is not supported, just text. EnterAct does not clip long lines, but folds the “hangover” back to the left margin on a new line. The line-break is not always as good as you yourself would do it, but at least you will never lose any characters off the right edge when printing. ---------------------------------------------------------- Options, under the Edit menu ---------------------------------------------------------- Introduction You can change any of the options at any time. Defaults for the options are shown in the figure above, and have been selected to give best performance under average conditions. Options are saved with EnterAct itself rather than a project. Some of them you’ll set once and forget, but the number of lookup windows and the number of entries per lookup determine how cluttered your screen can get, and how many alternate entries a lookup window will hold, so you’ll vary these two numbers to suit particular circumstances. For a discussion of “Safe switching under MultiFinder” please see the next chapter, “Switching to other applications”. Number of lookup windows This box allows you to set the maximum number of lookup windows that can appear on–screen at one time. For complicated situations you may want more than 4, whereas on a small screen you may prefer fewer than 4 to avoid clutter. Number of entries per lookup window The number in this box determines how may dictionary entries will be retrieved in a lookup window, if your spelling does not match any term in the dictionary exactly. If your spelling does match a term exactly, all exact matches will be retrieved, up to a maximum of 60. You may wish to temporarily increase the number in this box if your recollection of the spelling of a term is shaky. On a regular basis, you may prefer 3 or 5 entries rather than 4—a bit of experience will tell. Remembering window locations By default, EnterAct will remember the window locations of all your documents (saved in a small resource with the document). Also, you will not be asked if you want to save changes to a document when you close it if the only change is a change in window location (the “don’t pester” option). You can take advantage of the remembered window locations to work with groups of documents; arrange each group nicely on the screen, and then if you later reopen the documents in that group they will be arranged on–screen where you left them. Long or short windows If there is no remembered location for a document, or if you have switched off the “Save document window locations” option, then a newly–opened window will come up near the top of your screen, with a relatively short or long length according to what you select in the option “Windows open short/long by default”. You may not notice much of a distinction if you have a small screen. This short/long option always governs the appearance of new text windows, and of text files created by other applications that have never been saved while using EnterAct. Reformat Selection options Reformat Selection will rebreak the lines in a selection of text to improve the appearance of the right margin. Aside from selecting a “ragged right” or “full justification” look, you can also set the maximum number of characters per line in the “Reformat line width” box. The default of 74 gives a long but printable line in Monaco 9. Detect nested comment starts This option is on by default, meaning that EnterAct will accurately trap any single failure to properly start or end a comment, both while building your dictionary and while balancing. If you are in the habit of doubling up on comment starts, as in /*#define Flag37 /* if defined, use SlowDraw */ and if you are not willing to mend your ways, uncheck this option: comment starts within a comment will then be ignored for dictionary and balance purposes. Just make sure you type carefully! ---------------------------------------------------------- Switching to other applications ---------------------------------------------------------- Under the Finder There are some nifty INIT’s that will let you switch between applications under the Finder almost as quickly and easily as if you were using MultiFinder—On Cue and Master Juggler come to mind. Whatever means you employ to switch to another application from EnterAct while under the Finder, you will be asked if you wish to save any documents that need saving, and they will all be closed. The situation with MultiFinder is different , since documents can be left open when switching to another application. Under MultiFinder If you switch from EnterAct to some other application while under MultiFinder, you will not be required to close your documents. This means that while using the other application you could attempt to access documents that you have left open in EnterAct. If this potential conflict weren’t handled, you could end up working with two different versions of the same document, and inevitably you would lose one version. One solution to this problem would be to prevent you from opening that document with any other application if it is left open in EnterAct. This restrictive “my file and you can’t have it” attitude is appropriate if an application is meant for use on a network, where several people could want access to the same file at once. However, EnterAct is not meant to be used on a network, so it does not take this approach. Instead, when you switch, all open documents are quietly saved if they need saving and have ever been saved before (“untitled” documents present no problem—you can’t get at them with another application). In addition, when you return to EnterAct, EnterAct will check your disk to see if you have altered any of the open documents while you were away—if so, they will be quietly reloaded. EnterAct, if effect, opts for the “low man on the totem pole” position when it comes to having control over file access, and does the necessary behind–the –scenes work to allow you to leave files open and still be able to open and change them with other applications. To make this bulletproof, it will be safest if you close all text documents when leaving the other application, since that other application will typically not be able to compensate for files being changed “behind its back” in EnterAct. You can, if you wish, defeat this protection by unchecking the “Safe switching under MultiFinder” option in the Options dialog. However, EnterAct will not restrict access to open files when you switch, so you will be entirely responsible for ensuring that you don’t end up with two versions of the same file floating around. Closing all open text documents before switching would be sufficient. Safe switching protection can also be defeated on a per–switch basis, by holding down any of the <Shift>, <Option>, or <Command> modifier keys while you switch. Holding down a modifier key while you switch out from EnterAct means that unsaved changes to files will be left unsaved, and when you return to EnterAct any files open in EnterAct that were changed elsewhere will not be updated for you on–screen. Holding down a modifier key while returning to EnterAct will prevent just the updating on–screen of any files that were changed elsewhere—this is, on rare occasions, handy if you change a file with some other application, realise you’ve made a mistake bu can’t revert, and wish to recover the version of you file that’s still open in EnterAct. Check the disk for changes When you edit source (.c or .h) files that are in an EnterAct project with some other application, select Update Dictionary From Disk when you reopen the project to ensure that your dictionary is brought up to date, unless you clearly recollect that you didn’t change anything outside of a function body. This update typically takes only a few seconds. Only the project you have open will track which files are changed, so if you switch to a different project you will also need to select Update Dictionary From Disk to rebuild the dictionary if any .c or .h files in the project were changed while the project was not open, whether or not the files were changed with EnterAct. Conversely, when you switch to THINK C after a session of editing with EnterAct, select THINK C’s Make command and click the “Use Disk” button followed by the “Make” button to bring your THINK C project up to date. This may add 10 or 20 seconds to the recompile that you will have to do anyway after editing source files. If you remember exactly which files were changed, you can instead select them one by one in the project window and use the “Compile” command to update your THINK C project. Other applications that employ a project concept involving source files may also require that you issue some sort of check–the–disk command to bring things up to date. ---------------------------------------------------------- Lookup tips ---------------------------------------------------------- Looking up your notes Here’s how to build your own hard–won notes and observations about programming the Macintosh into your dictionary, for quick retrieval by name. Note files consist of fake structs, the sole content of each struct being a comment which contains the specific note. Suppose, for example, one of your notes concerns getting and using the modification date (“modDate”) for a file. To be able to retrieve the note, you first need to give it a memorable name, such as “modDateNote”. Then, in your note file, you would set up the dictionary entry like this: struct modDateNote { /* Paste the note in here, within a comment that makes up the entire "struct" body. */ }; /* actually, the semicolon is optional */ The note goes inside a comment, which makes up the body of a struct. Placing the note inside a comment is necessary, because the dictionary–builder checks for proper balance of some delimiters within the body of a struct. It remains only to persuade EnterAct to build such a file into your dictionary. EnterAct will do so for files that are in the left or middle pane of your project, and by default if a file name ends in “.c” or “.h” it is added to the left or middle pane respectively. However, a slightly nicer approach is to give your note files an ending that describes what they are. A reasonable choice would be “Notes”, and then your note files would have names like “File.Notes”, “Memory.Notes”, “DA.Notes”. To instruct EnterAct that files with names ending in “Notes” should go in the left or middle pane, the last step is to select the File Extensions command and type in the file extension (eg “Notes”) that you choose for your note files—see the “Custom file extensions” section on page 28 for an example. Which pane these files go in (left or middle) is up to you. Now add the note files to your project, select Update Dictionary, and you can retrieve any note by typing its name in any text window and pressing <Enter>. If the name of the struct consists of the exact topic followed by “Note” then it will be easy to remember. And if you place a comment in your source code containing the name of the note, such as /* see modDateNote */ , then all you have to do is click to the right of the note name and press <Enter>. A note can be of any length, and if you edit it heavily you can probably clean up the appearance afterwards with Reformat Selection. When in doubt If you’re sure that a term should be in your dictionary, but can’t retrieve any entry for it, see the “Lookup problems” section in the last chapter, “If there’s a problem”. It’s difficult to come up with memorable names for absolutely everything, and on rare occasions you may find yourself trying to look up a function or struct, and not remember a darn thing about the name you gave it. For that matter, the names of toolbox things aren’t always stunning in their clarity, either. When this happens, sometimes it helps to type a guess and press <Enter>, even if you’re sure that you’re off by a mile. EnterAct doesn’t know that, and will retrieve the best matches for what you typed anyway. This “free association” may help jog your memory. Some words, such as “Pointer”, are spelled out in full in some uses, but abbreviated in others (in the toolbox, you’ll find ATPreqPointer and NewPtr). If you were to type NewPointer<Enter> for example, you probably wouldn’t be able to retrieve lookup for NewPtr, since the lookup function would count things like ATPreqPointer as being a “better” match. So, if the full spelling of a name doesn’t work, try abbreviating any commonly–occurring part(s) of the name. And of course, if you try the abbreviation first without success, try spelling the whole thing out. As an odd example, DisposeHdle<Enter> probably won’t retrieve DisposHandle, because there will probably be terms in your dictionary containing Dispose spelled out fully (with the “e” on the end), and EnterAct will score these as better matches. A run of matching characters always counts more than bits and pieces that match, so if you’re after an abbreviated name but spell it out in full you may accidentally retrieve terms that match the fully–spelled out version. Note that DisposeHandle<Enter> would retrieve DisposHandle, as a result of the much higher score resulting from spelling out Handle in full. This abbreviation versus full–spelling choice will only rarely be a problem, but you should keep it in the back of your mind. ---------------------------------------------------------- Seeing where a term is defined ---------------------------------------------------------- <Option>double–click To see the file in which any dictionary term is defined, hold down the <Option> key while double–clicking on the term. EnterAct will enter the term in the Find dialog (the equivalent of Enter Selection), open the file where the term is defined, and scroll to the first instance of the term in the file. Except for functions, methods, structs, classes, unions, and enums, for which you’ll almost always be scrolled to the exact defining instance, with no tripping over a mention in a comment or variable declaration or prototype. Since a double–click selects just one word, this approach doesn’t work with “full” method names that contain colons: the menu command Find Selection is provided for these cases, discussed also in the “Browsing” chapter. Find Definition When you want to see the defining instance of a method, select the entire name on both sides of the two colons and then pick Find Selection. This does the same thing as <Option> double–click, but also works with names that consist of more than one word. If a particular method name is used in several classes, EnterAct won’t know which method you want to see the definition of if you just <Option>double–click on the method name. To pick a specific method, click to the right of the method name and press <Enter>. The resulting lookup window will contain entries for all methods with that name: advance to the one you want by pressing <Enter> repeatedly. Then select the entire class name, colons, and method name and pick Find Definition. For an illustration, see the “Browsing” chapter. Find Definition ignores trailing spaces or tabs, and also accepts hint characters in much the way that lookup does—see just below. If there are multiple definitions <Option>double–click or Find Definition will show only a single defining instance of a term. However, Find Definition will accept a hint character after the term to be found, and this will at least limit the defining instance to one type of thing (function, typedef, define etc). For example, if you had both a function and a typedef named “FileStuff” then applying Find Definition to all of “FileStuff(” would find the defining instance of the function, whereas applying it to the selection “FileStuff t” would bring up the defining instance of the typedef. Hint characters are listed and described in “Lookup” chapter, in the “Hints for speedup” section. To make the hint work with Find Definition, type it after the term you want found (a space is needed if the hint is a letter), then select the term and the hint before issuing the Find Definition command. If there are multiple definitions of a term that are of the same type (eg several functions with the same name) and you wish to see them, you’ll have to do a multi–file search on the term and pick out the defining instances yourself. When your project consists of several applications blended together, you can minimze multiple–definition confusion by not adding any files that you definitely don’t need. ---------------------------------------------------------- Some thoughts on using EnterAct ---------------------------------------------------------- Projects are cheap EnterAct projects are quick and easy to create, the only real penalty being the amount of disk space used. While an EnterAct project can be truly enormous and still be usable, lookup will be faster and more appropriate if you tailor your project to the problem at hand. As an extreme example, here’s a generic project that would be perfectly suitable for developing file–handling functions: Lookup in this size project will always be instantaneous no matter how bad your spelling, and lookup for your terms will never be confused by accidental matches against terms in files that you don’t need reference to. While accidental matches are not common, the speed of lookup when your spelling is not exact does depend directly on the size of your dictionary. The rule of thumb then is that an EnterAct project can consist of whatever files you want, but performance will be better if you don’t add files that you don’t need. There is a tradeoff between having absolutely everything of potential interest in a large, sluggish project, and having several smaller but better–performing projects. Performance for a given project is determined by the speed of your particular Macintosh, and a bit of experience should quickly provide you with a guide as to how ruthless to be about trimming unnecessary files. Roughly speaking, you’ll be interested in minimizing dictionary size if you have a Mac Plus, less so with an SE, and hardly ever if you have a Mac II or faster. Learning from or reviewing code If your purpose is to explore rather than create, then you won’t be typing in many incorrect spellings. Lookup when spelling is correct is always instant, which is the case if you’re just reading through code and looking up terms in the code with a click–and–<Enter> or Find Definition for the terms as you go. In this case the only restrictions on the size of the project are the amount of disk space and RAM needed, and you can add absolutely all files related to the application without slowing down the lookup, no matter what model your Macintosh is. If lookup is too slow As mentioned above, there is a tradeoff between having lookup for absolutely everything and having fast lookup. In general, the faster your Macintosh is the more you can throw into your dictionary. If you have a slower Macintosh, it will pay especially to add to your project only those toolbox headers in the “Mac #includes” folder that you really need. SANE.h, for example, is loaded with enum constants, constants that you’ll need access to only if you’re doing tricky floating–point stuff. If you take an extra minute to avoid adding files to your project that you don’t need you can greatly improve lookup performance, especially on a Mac Plus. Supplying a “hint” when you want a term looked up can improve lookup speed, but this is in general a second–best solution since you have to type one or two extra characters for the lookup. See the “Hints for speedup” section in the “Lookup” chapter for details. Balance your files Balancing all of your source files at the end of development will weed out any nasty errors involving improperly–terminated comments that THINK C’s compiler didn’t catch. To balance a whole file at once, select an insertion point at the top of the file and then select Balance. However, if you bring your dictionary up to date at the end of development, then all of the source files in your project will have automatically been checked for all detectable comment errors as a byproduct of dictionary–building. So, you need only check files that will be included in your THINK C project but are not included in your EnterAct project. If it moves, document it EnterAct was designed with the hurried, lazy “document it when you think of it or forget it” programmer in mind (myself among them). I can’t abide inching through the folder maze to get at a file—in the old days before EnterAct, I actually found it simpler to keep most of my specification, design, test, and usage notes on paper. A lot of paper. No more. Now, by adding all of my documentation to my project, I can retrieve my notes on something quickly enough that it’s more convenient than leafing through paper—and more importantly for me, fast enough that I haven’t forgotten why I wanted to see the note by the time I dig it up! It can be handy to start off the name of each document with an abbreviation describing what general type it is, and set up a folder in each project for each type. For example, in my “EnterAct” project folder there is an “EnterAct Design” folder containing the documents “D_general”, “D_cursors”, “D_files”, “D_options”, “D_undo”, “D_dictionary”, “D_lookup” etc. Starting each design document with “D_” for Design groups them together in the alphabetically–ordered plain text pane in my project. To scroll to the list of design documents within the plain text pane, I click in the rightmost pane to activate it and press <d>. Important usage notes are “disguised” as struct’s, as described in the “Lookup tips” chapter—so if I want to look at my note on wrestling with Quickdraw regions I type “RegionNote<Enter>” to see it, without having to even remember what file I put it in (this one I put in “THINK C: Mac Notes: _Quickdraw.Notes”—and, of course, I added all my “Mac Notes” to the project with the Add All In Folder command before updating the dictionary). For example , if ((**availRgn).rgnSize > 10) /* see RegionNote */ { yPos = 5; y = *(((int *)(*availRgn)) + yPos); while (y != 32767) { xPos = yPos + 1; ...etc might look like Greek to me if I come back to review it, but by clicking to the right of RegionNote in the comment and pressing <Enter> I can view my hard–won note on regions that explains in detail what’s going on: (nice picture in printed manual...) EnterAct’s main attraction at present is the dictionary/lookup capability, but in a more general way EnterAct is intended to increase your ability to handle complexity when creating or reviewing C code by making the computer do the routine chores so that you can get on with the Big Picture. This version is not the final answer. I’m thinking that EnterAct version two will add some automatic code generation and documentation capabilities, but if you have some thoughts of your own on what version two might do, please drop me a line. ---------------------------------------------------------- If there's a problem ---------------------------------------------------------- Out of memory If you run out of memory while trying to do something, you’ll see an Alert saying “Out of memory. Please close up and try again when things are less busy.” or the equivalent. Open windows and Desk Accessories all take up memory that you can free by closing the window or DA. The project especially can take a lot of memory, since the entire dictionary associated with it is kept in memory. If you encounter frequent “Out of memory” messages, the least inconvenient but most expensive cure is to add more memory to your Macintosh. However, you can often free up a considerable amount of memory by removing relatively unneeded files from your project. The rough rule is that your project dictionary will take up in memory about one–half of the disk space used by all .c and .h files in the project. If you don’t need lookup for any of the terms in a .c or .h file, removing it from your project will free up some memory. Note that plain text files in the rightmost pane do not greatly affect memory used, since they are not incorporated into the dictionary. Of course, if you’re running under MultiFinder the problem may just be that you don’t have a big enough partition allocated for EnterAct. To fix this, pick Get Info for EnterAct while in the (Multi)Finder and type in a larger “Application Memory Size”. A rough minimum is 300K plus 4/3 times the disk space used by your project file after the dictionary has been built. Missing dictionary entries In rare cases, an error in your source may lead to a term not being recorded in your dictionary, with no message. An example is int x /* missing semicolon */ long y; for which EnterAct would record only the “y”, missing the “x”. This is the one time that EnterAct’s tolerance of errors can be a nuisance, but if you can remember where the term is defined then visual inspection should reveal the error, typically a missing semicolon or a missing or misspelled keyword. If you can’t remember where the term is defined, and you really want lookup to be available for it, then the one sure cure is to switch to THINK C and Compile or Check Syntax until you spot and fix the bug. Dictionary build problems If the dictionary–builder trips over a bug in your code and you can’t spot the problem, your next best course of action is to switch to THINK C and compile the offending file. If you call for technical support and your code is not compilable, there is only a small chance that I’ll be able to help you, since the possibilities would be too open–ended. Look on the bright side, you’ll have to compile your code sooner or later anyway. EnterAct sets moderately strict standards for the part of your code that is outside of a function, struct, or union body. However, code that is inside of a function, struct, or union body is checked only for proper balance in a few key delimiters, typically {}, (), and /* */. As a result, almost all of your first–draft errors will be simply ignored. Some errors outside of a body can be compensated for, and the remainder that do trigger a complaint from the dictionary–builder will almost always be fairly obvious. You’ll know you have a dictionary build problem if you see one of the messages below after selecting Update Dictionary, Update For Front File Only, or Update Dictionary From Disk. Statement too complex to deal with all at once. Any chance you could simplify? This message should be rather rare. You would have to nest brackets more than 200 deep, or have more than 256 enum constants in a single enum in order to produce it. I’m not giving an example! The cure would be to reduce the number of brackets in your deeply–nested construction, or split a monstrous enum into two parts. Typedef cannot have an init. One or the other has to go. typef int SHORT = 7; This should prove rare. “typedef” essentially creates a new keyword, and you can no more initialize it than you could initialize “int” itself. Apologies for stating the obvious. Illegal word or punctuation after struct or union. struct int myStruct {... /* int */ struct /myStruct {... /* the '/' */ struct myStruct (...} /* wrong bracket */ Something between “struct” or “union” and the opening left brace (if any) of the body doesn’t belong. Or, you may have neglected to type in a name for the struct or union. Illegal word or punctuation after enum. enum Numbers int {... /* int */ enum /Numbers {... /* the '/' */ enum Numbers {one two three}; /* missing commas */ enum Numbers {one, two; three}; /* that first semicolon */ Includes all the sorts of errors for a “struct” or “union”, and also any error inside the body of the enum where the enum constants are listed. EnterAct does not record any terms inside a struct or union, but does record all enum constants, hence checking for an enum is more strict. Some errors (such as an extra comma) can be shrugged off, but most others will trigger this message. #if has no matching #endif, #else, or #elif. I’m afraid you’re on your own tracking this error down, since it could be anywhere in the file after the position shown. It could be due to a misspelling, such as #eles, or the necessary “if–ender” could be missing altogether. Function(?) has no name. long (int x, char *tPtr); So, give the poor function a name. Pascal must be followed by a function. “Pascal” or “pascal” indicates that a function passes arguments and returns a value according to Pascal rather than C conventions. For more on this topic, see your THINK C manual. Couldn't find end of initialization. struct MyStruct {int x; long y} instance = {4, 7L; Typically this is caused by a missing or extra '}', as in the above example. It could also be caused by a missing semicolon. Unbalanced statement. Use the Balance command right after OK'ing this alert to diagnose the problem. Since the Balance command checks all delimiters and shows you at least one end of an unbalanced construction, finding the typo that caused the lack of balance is usually straightforward. Selecting Balance a second time can be useful—after the second Balance either you’ll be shown a mismatch for the first delimiter or you’ll hear a beep indicating that the other end is completely missing. Unbalanced or nested comment. Use the Balance command right after OK'ing this alert to diagnose the problem. EnterAct’s comment checking while dictionary–building (and balancing) is even stricter than most compilers. For details, see the “Nested and bad comments” section in the “Balance” chapter. As a byproduct of dictionary–building, all source files in your project will be thoroughly checked for comment errors. If the problem is due to consecutive comment starts, and you want to keep them because that’s the way you do things, select Options from the Edit menu and uncheck the “Detect nested comment starts” check box. This will partially disable EnterAct’s ability to trap comment problems, both when building your dictionary and when balancing. Lack of balance in parentheses (). Use the Balance command right after OK'ing this alert to diagnose the problem. See above, Unbalanced statement.... Unbalanced single or double quotes. Use the Balance command right after OK'ing this alert to diagnose the problem. See above, Unbalanced statement.... Unbalanced square brackets []. Use the Balance command right after OK'ing this alert to diagnose the problem. See above, Unbalanced statement.... Left curly brace { is not preceded by struct, union, enum, =, or function definition. typedef stork MyStruct {int x; long y};/* stork?struct? */ long ShouldBeFunction{int x, long y); /* '{' vs '(' */ Either the '{' should be something else, such as a '(', or a keyword just before the '{' is missing or badly misspelled. EnterAct can handle some typo’s, such as typdef sturct... but at some point (such as twerpdeaf stork) has to give up and complain. Colon must signal class name, method name, or low-memory global. Note this exludes some uses of the colon which are irrelevant for dictionary–building, such as bit fields and any usage inside a function body. Something is wrong at or near the position shown. The error makes the statement nothing like C, and should be fairly obvious. A Shakespearean sonnet will trigger this message. In general, the error lies outside of EnterAct’s area of competence. Check for typo’s at or near the position shown in the file. This message corresponds to the “Syntax error” message that compilers issue when they give up and don’t have a clue what’s going on. My favourite way to generate this error is to accidentally add a junk file with a name ending in .c or .h to a project. Remember, Add All In Folder inhales every text file in a folder. Function body was expected but not found at the position shown. This typically results from a missing left brace '{' at the start of a function. Rarely, it can be caused by an excess semicolon in an “old–fashioned” style function definition, between the list of arguments in round brackets and the start of the function body, eg: int myFunc(x,y) int x; long y;; /* extra semicolon */ {...} The dictionary–builder counts up your arguments, and won’t allow more semicolons than you have arguments. Lookup problems There is a complementary guide to solving lookup problems at the end of the “Lookup” chapter. The last section of the “Lookup tips” chapter might also be of help. The term is in your dictionary but you can’t remember the spelling well enough to retrieve it? Virtually every name in your dictionary will have some distinctive part that uniquely identifies it, both from your point of view and EnterAct’s. However, three natural ways of misremembering can throw off your attempt to retrieve a definition; synonyms (ReadKeys vs GetKeys), abbreviations (NewPointer vs NewPtr), and reversals (FreeMem vs MemFree). These alterations will affect lookup if they involve the distinctive part of the name, or the name has no distinctive part at all, or if you also omit typing the distinctive part. The rule of thumb is that if the term you want lookup for consists entirely of common words used in many names you will have to be more accurate with your spelling to help EnterAct distinguish among the possibilities. By the way, with EnterAct you should find that the benefits of using long, descriptive names outweigh any drawbacks. The combination of lookup with Paste Selection Behind will let you work with long names almost as easily as with short ones in terms of total typing required, and longer names will be both easier for you to understand at a glance and easier for EnterAct to distinguish when looking for matching entries in your dictionary. You know the term should be in your dictionary but even typing its exact name doesn’t retrieve it? This is rare, and is caused by EnterAct mishandling an error in your source code, in an attempt to compensate for first–draft errors without bothering you. Looking at the statement where the term is defined or mentioned in your source code will usually reveal a simple error such as a missing semicolon or a misspelled keyword. If not, switch to THINK C and compile your code until you’ve cleared any bugs in the statement where the term occurs. Balance problems If lack of balance is caused by mismatched delimiters, such as '{' matched against ']', then by repeatedly selecting Balance you can toggle between the two mismatched delimiters. If the unbalance is due to a missing delimiter, keep in mind that EnterAct handles comments properly, so the error will not be due to an extra delimiter inside a comment. For example, a comment such as /* 1) load 2) decrement 3) store */ won’t trigger an error, unless you start with an insertion point or selection that is inside the comment. If you’re attempting to balance a closing delimiter and Balance has to run backwards through an “asm {..}” block while searching for the matching opener, you might get a spurious error due to something in an assembly–language comment—see the “Balance” chapter in “The asm problem” section for details. If the problem is due to consecutive comment starts, and you want to keep them because that’s the way you do things, select Options from the Edit menu and uncheck the “Detect nested comment starts” check box. This will partially disable EnterAct’s ability to trap comment problems, both when building your dictionary and when balancing. *********END OF DISK MANUAL************* Tech support: 1-416-595-9440